feat: BGM system, NPC bonds, save/load, progress bar, UI polish

- Background music: 6 mood tracks, set_music directive, crossfade transitions
- NPC-NPC relationship system: directed bonds, bond graph in Relations tab
- Save/load: file-based JSON save with journal history + audio settings
- Two-phase start: /start_text (LLM) then /start_images (painter) with real progress bar
- Relations tab: directed bond list (A->B and B->A shown separately)
- Settings panel: BGM + TTS volume sliders, save button
- Bond graph: semantic color (jealousy=red, camaraderie=green), no player node
- Fix: UnicodeEncodeError in ModalLLM print (cp1252 safe)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -32,3 +32,4 @@ memory/
 .python-version
 
 uv.lock
+frontend/music/*.mp3

app.py

@@ -163,6 +163,10 @@ def build_server():
     app = Server()
     # serve generated images (backdrops/sprites) as static files at /images/<name>
     app.mount("/images", StaticFiles(directory=str(config.CACHE_DIR)), name="images")
+    # serve background music tracks at /music/<name>.mp3|ogg
+    _music_dir = Path(__file__).parent / "frontend" / "music"
+    _music_dir.mkdir(exist_ok=True)
+    app.mount("/music", StaticFiles(directory=str(_music_dir)), name="music")
 
     @app.get("/", response_class=HTMLResponse)
     async def home() -> str:
@@ -177,6 +181,18 @@ def build_server():
     def start(theme: str = "school", tone: str = "romantic", seed: int | None = None) -> dict:
         return ENGINE.start(SetupForm(theme=theme, tone=tone, seed=seed)).model_dump()
 
+    @app.api(name="start_text")
+    @gpu
+    def start_text(theme: str = "school", tone: str = "romantic", seed: int | None = None) -> dict:
+        """Phase 1 — LLM init only. Returns text-only ViewState (no images)."""
+        return ENGINE.start_text(SetupForm(theme=theme, tone=tone, seed=seed)).model_dump()
+
+    @app.api(name="start_images")
+    @gpu
+    def start_images() -> dict:
+        """Phase 2 — paint backdrop + sprite. Call after start_text."""
+        return ENGINE.start_images().model_dump()
+
     @app.api(name="turn")
     @gpu
     def turn(player_input: str, action: str = "talk", target: str = "") -> dict:

frontend/index.html

@@ -143,9 +143,77 @@
   @keyframes pulse-rec{0%,100%{opacity:1}50%{opacity:.6}}
   #mic.live{background:var(--rose); animation:pulse-rec 1.2s ease-in-out infinite}
   #mic.waiting{background:rgba(255,255,255,.12); color:var(--ink-dim); cursor:wait}
-  #tts-toggle{min-width:42px; background:transparent; color:var(--ink-dim);
-    border:1px solid rgba(255,255,255,.22); font-size:1.1rem}
-  #tts-toggle.active{color:var(--gold); border-color:rgba(232,193,114,.5)}
+  /* ---- settings button ---- */
+  #settings-btn{
+    position:fixed; top:56px; left:16px; z-index:8;
+    display:flex; align-items:center; gap:7px;
+    background:rgba(10,13,24,.82); border:1px solid rgba(232,193,114,.30);
+    border-radius:10px; padding:9px 14px;
+    color:var(--ink-dim); font-family:var(--display); font-size:1rem;
+    backdrop-filter:blur(6px); cursor:pointer;
+    transition:background .15s, border-color .15s, color .15s, transform .15s;
+  }
+  #settings-btn:hover{
+    background:rgba(232,193,114,.10); border-color:rgba(232,193,114,.5);
+    color:var(--gold); transform:translateY(-1px);
+  }
+  /* ---- settings overlay ---- */
+  #settings-overlay{
+    display:none; position:fixed; inset:0; z-index:35;
+    background:rgba(0,0,0,.55); backdrop-filter:blur(4px);
+    align-items:center; justify-content:center;
+  }
+  #settings-overlay.open{display:flex}
+  #settings-panel{
+    width:min(380px,90vw); background:var(--dusk-1);
+    border:1px solid rgba(232,193,114,.25); border-radius:16px;
+    padding:28px 28px 24px; box-shadow:0 8px 40px rgba(0,0,0,.5);
+  }
+  #settings-header{
+    display:flex; align-items:center; justify-content:space-between; margin-bottom:24px;
+  }
+  #settings-header h3{
+    font-family:var(--display); font-size:1.2rem; color:var(--gold); font-weight:600;
+  }
+  #settings-close{
+    background:none; border:none; color:var(--ink-dim); font-size:1.1rem;
+    padding:4px 8px; cursor:pointer; border-radius:6px;
+  }
+  #settings-close:hover{color:var(--ink)}
+  .settings-row{
+    display:flex; align-items:center; gap:12px; margin-bottom:20px;
+  }
+  .settings-row label{
+    font-family:var(--display); font-size:.9rem; color:var(--ink); min-width:120px; flex-shrink:0;
+  }
+  .settings-row input[type=range]{
+    flex:1; -webkit-appearance:none; appearance:none;
+    height:4px; border-radius:2px; background:rgba(255,255,255,.15); outline:none; cursor:pointer;
+  }
+  .settings-row input[type=range]::-webkit-slider-thumb{
+    -webkit-appearance:none; appearance:none;
+    width:16px; height:16px; border-radius:50%;
+    background:var(--gold); cursor:pointer; box-shadow:0 0 4px rgba(232,193,114,.4);
+  }
+  .settings-row input[type=range]::-moz-range-thumb{
+    width:16px; height:16px; border-radius:50%; border:none;
+    background:var(--gold); cursor:pointer;
+  }
+  .settings-vol-val{
+    font-family:var(--body); font-size:.82rem; color:var(--ink-dim);
+    min-width:36px; text-align:right;
+  }
+  .settings-divider{
+    border:none; border-top:1px solid rgba(232,193,114,.1); margin:20px 0;
+  }
+  #settings-save-btn{
+    width:100%; padding:13px; font-size:1rem; font-family:var(--display);
+    background:rgba(232,193,114,.12); border:1px solid rgba(232,193,114,.4);
+    border-radius:10px; color:var(--gold); cursor:pointer; letter-spacing:.3px;
+    transition:background .15s;
+  }
+  #settings-save-btn:hover{background:rgba(232,193,114,.22)}
+  #settings-save-btn:disabled{opacity:.5; cursor:wait}
   /* ---- book intro overlay ---- */
   #intro-book{
     position:fixed; inset:0; z-index:30; display:flex; align-items:center; justify-content:center;
@@ -205,6 +273,16 @@
     border:1px solid rgba(255,255,255,.18); border-radius:10px; padding:10px 12px; font-family:var(--body)}
   select option{background:var(--dusk-2); color:var(--ink)}
   #enter{width:100%; margin-top:16px; padding:14px; font-size:1.05rem}
+  #start-progress{margin-top:18px; display:none; text-align:left}
+  .sp-step{margin-bottom:12px}
+  .sp-step-header{display:flex; justify-content:space-between; align-items:baseline; margin-bottom:5px}
+  .sp-step-label{font-size:.78rem; font-family:var(--display); color:var(--gold); letter-spacing:.04em}
+  .sp-step-pct{font-size:.75rem; color:var(--ink-dim)}
+  .sp-track{height:5px; border-radius:3px; background:rgba(255,255,255,.08); overflow:hidden}
+  .sp-fill{height:100%; border-radius:3px; width:0%; transition:width .55s ease}
+  .sp-fill.phase-llm{background:linear-gradient(90deg,#b08a4a,var(--gold))}
+  .sp-fill.phase-img{background:linear-gradient(90deg,#6a9cc8,#a8d4f0)}
+  .sp-note{font-size:.78rem; color:var(--ink-dim); font-style:italic; margin-top:4px; min-height:1.1em; transition:opacity .35s}
   .shimmer{color:var(--ink-dim); font-style:italic}
   .hidden{display:none !important}
   /* ---- journal button (top-right) ---- */
@@ -333,6 +411,22 @@
   .rel-score.neg{color:var(--rose)}
   .rel-score.zero{color:var(--ink-dim)}
   .rel-offstage{font-size:.7rem; color:rgba(200,190,175,.75); font-style:italic}
+  .rel-section-title{
+    font-family:var(--display); font-size:.72rem; color:var(--gold); opacity:.65;
+    letter-spacing:1.2px; text-transform:uppercase;
+    padding:14px 0 6px; border-bottom:1px solid rgba(232,193,114,.12); margin-bottom:8px;
+  }
+  .bond-graph-wrap{
+    padding:8px 0 8px; display:flex; justify-content:center;
+  }
+  .bond-graph-wrap svg{ width:100%; max-height:280px; display:block; overflow:visible }
+  .bond-list{ padding:0 4px 12px }
+  .bond-pair{ margin-bottom:7px; padding:5px 9px; background:rgba(255,255,255,.04); border-radius:7px }
+  .bond-row{ display:flex; align-items:center; gap:5px; padding:2px 0; font-size:.78rem }
+  .bond-name{ font-family:var(--display); min-width:56px; color:var(--ink); white-space:nowrap; overflow:hidden; text-overflow:ellipsis }
+  .bond-arrow{ color:var(--ink-dim); flex-shrink:0; font-size:.7rem }
+  .bond-note{ font-style:italic; flex:1; font-size:.73rem }
+  .bond-val{ font-family:var(--display); font-weight:600; min-width:30px; text-align:right; font-size:.78rem }
 </style>
 </head>
 <body>
@@ -357,11 +451,35 @@
         <input id="say" placeholder="say something…" autocomplete="off" />
         <button id="send">✓</button>
         <button id="mic" class="ghost" title="hold to speak">🎙️</button>
-        <button id="tts-toggle" title="toggle voice output">🔇</button>
       </div>
     </div>
   </div>
 
+  <!-- Settings button — hidden until game starts -->
+  <button id="settings-btn" class="hidden" title="Settings">⚙️</button>
+
+  <!-- Settings overlay -->
+  <div id="settings-overlay">
+    <div id="settings-panel">
+      <div id="settings-header">
+        <h3>⚙️ Settings</h3>
+        <button id="settings-close">✕</button>
+      </div>
+      <div class="settings-row">
+        <label>🎵 Music</label>
+        <input type="range" id="bgm-vol-slider" min="0" max="100" value="35" />
+        <span class="settings-vol-val" id="bgm-vol-val">35%</span>
+      </div>
+      <div class="settings-row">
+        <label>🔊 Voice</label>
+        <input type="range" id="tts-vol-slider" min="0" max="100" value="100" />
+        <span class="settings-vol-val" id="tts-vol-val">100%</span>
+      </div>
+      <hr class="settings-divider" />
+      <button id="settings-save-btn">💾 Save current game</button>
+    </div>
+  </div>
+
   <!-- Journal button — hidden until game starts -->
   <button id="journal-btn" class="hidden" title="Story journal">
     <span class="jb-icon">📖</span>
@@ -373,12 +491,7 @@
   <div id="journal-overlay">
     <div id="journal-header">
       <h3>📖 Journal</h3>
-      <div style="display:flex;gap:8px;align-items:center">
-        <button id="download-save-btn" title="Download save file" style="background:none;border:1px solid rgba(232,193,114,.3);
-          border-radius:6px;color:var(--gold);padding:4px 10px;font-size:.82rem;cursor:pointer;
-          transition:background .15s" class="hidden">💾</button>
-        <button id="journal-close" title="Close">✕</button>
-      </div>
+      <button id="journal-close" title="Close">✕</button>
     </div>
     <div id="journal-tabs">
       <button class="jtab active" data-tab="story">Story</button>
@@ -430,6 +543,24 @@
       <div class="field"><label>Theme</label><select id="theme"></select></div>
       <div class="field"><label>Tone</label><select id="tone"></select></div>
       <button id="enter">Enter the story</button>
+      <div id="start-progress">
+        <div class="sp-step" id="sp-step-llm">
+          <div class="sp-step-header">
+            <span class="sp-step-label">✦ Writing the story</span>
+            <span class="sp-step-pct" id="sp-pct-llm">0%</span>
+          </div>
+          <div class="sp-track"><div class="sp-fill phase-llm" id="sp-fill-llm"></div></div>
+          <div class="sp-note" id="sp-note-llm">Waiting for the AI…</div>
+        </div>
+        <div class="sp-step" id="sp-step-img" style="opacity:.35">
+          <div class="sp-step-header">
+            <span class="sp-step-label">🎨 Painting the scene</span>
+            <span class="sp-step-pct" id="sp-pct-img">—</span>
+          </div>
+          <div class="sp-track"><div class="sp-fill phase-img" id="sp-fill-img"></div></div>
+          <div class="sp-note" id="sp-note-img">Starts once the story is written</div>
+        </div>
+      </div>
     </div>
   </div>
 
@@ -455,8 +586,9 @@ let client;
 // --- journal ---
 let history = [];
 let journalTurn = 0;
-let knownChars = [];  // updated each render with known_characters from ViewState
-const spriteCache = {};  // id → last known sprite_url (persists when char goes off-stage)
+let knownChars = [];   // updated each render with known_characters from ViewState
+let npcBonds = [];     // updated each render with npc_bonds from ViewState
+const spriteCache = {};  // id -> last known sprite_url (persists when char goes off-stage)
 
 const ACTION_ICONS = { talk:"💬", flirt:"🌸", touch:"🤝", ask:"🤔", silent:"😶", give:"🎁", move:"🚪" };
 
@@ -502,9 +634,10 @@ function renderRelations() {
     panel.innerHTML = '<div class="je-empty">No characters met yet��</div>';
     return;
   }
-  // Sort: on-stage first, then by relationship desc
+
+  // --- section 1: player↔NPC bars ---
   const sorted = [...knownChars].sort((a, b) => b.relationship - a.relationship);
-  panel.innerHTML = sorted.map(ch => {
+  const barsHtml = sorted.map(ch => {
     const rel = ch.relationship ?? 0;
     const posW = rel > 0 ? rel.toFixed(1) : "0";
     const negW = rel < 0 ? Math.abs(rel).toFixed(1) : "0";
@@ -515,11 +648,10 @@ function renderRelations() {
       ? `<img src="${spriteUrl}" alt="${ch.name}" />`
       : `<span>👤</span>`;
     const isPresent = (window._presentIds || []).includes(ch.id);
-    const statusText = isPresent ? "on stage" : "away";
     return `<div class="rel-entry">
       <div class="rel-avatar">${avatarHtml}</div>
       <div class="rel-info">
-        <div class="rel-name">${ch.name} <span class="rel-offstage">${statusText}</span></div>
+        <div class="rel-name">${ch.name} <span class="rel-offstage">${isPresent ? "on stage" : "away"}</span></div>
         <div class="rel-mini-bar">
           <div class="rel-mini-neg" style="width:${negW}%"></div>
           <div class="rel-mini-pos" style="width:${posW}%"></div>
@@ -528,6 +660,142 @@ function renderRelations() {
       <span class="rel-score ${scoreClass}">${label}</span>
     </div>`;
   }).join("");
+
+  // --- section 2: NPC↔NPC bond graph + directed list ---
+  let graphHtml = "";
+  if (knownChars.length >= 2) {
+    // Group bonds by unordered pair so we can show both directions together
+    const pairMap = {};
+    for (const b of npcBonds) {
+      const key = [b.source_id, b.target_id].sort().join("|");
+      if (!pairMap[key]) pairMap[key] = [];
+      pairMap[key].push(b);
+    }
+    const bondListHtml = Object.values(pairMap).map(pairBonds => {
+      const rows = pairBonds.map(b => {
+        const col = _bondColor(b.note, b.value);
+        const sign = b.value > 0 ? "+" : "";
+        const noteStr = b.note ? b.note : (b.value === 0 ? "neutral" : "");
+        return `<div class="bond-row">
+          <span class="bond-name">${b.source_name}</span>
+          <span class="bond-arrow">→</span>
+          <span class="bond-name">${b.target_name}</span>
+          <span class="bond-note" style="color:${col}">${noteStr}</span>
+          <span class="bond-val" style="color:${col}">${sign}${b.value}</span>
+        </div>`;
+      }).join("");
+      return `<div class="bond-pair">${rows}</div>`;
+    }).join("") || `<div class="je-empty" style="font-size:.78rem">No bonds recorded yet</div>`;
+
+    graphHtml = `<div class="rel-section-title">Between them</div>
+      <div class="bond-graph-wrap">${_buildBondGraph(knownChars, npcBonds)}</div>
+      <div class="bond-list">${bondListHtml}</div>`;
+  }
+
+  panel.innerHTML =
+    `<div class="rel-section-title">With you</div>${barsHtml}${graphHtml}`;
+}
+
+// Semantic coloring: note keywords override the numeric value
+const _NEG_NOTE = /jealou|rival|resent|env[iy]|bitter|hostil|scorn|distrust|spite|hate|anger/i;
+const _POS_NOTE = /fond|loyal|protect|admire|camaraderie|trust|warm|friend|love|cherish/i;
+function _bondColor(note, value) {
+  if (note && _NEG_NOTE.test(note)) return "#c87e7e";
+  if (note && _POS_NOTE.test(note)) return "#7ec8a0";
+  return value >= 0 ? "#7ec8a0" : "#c87e7e";
+}
+
+function _buildBondGraph(chars, bonds) {
+  const W = 340, H = 280, cx = W / 2, cy = H / 2;
+  // Use a larger radius now that there's no center player node to avoid
+  const R = Math.min(cx, cy) - 44;
+
+  // Position NPCs in a circle
+  const nodes = chars.map((ch, i) => {
+    const angle = (2 * Math.PI * i / chars.length) - Math.PI / 2;
+    return {
+      id: ch.id, name: ch.name,
+      x: cx + R * Math.cos(angle),
+      y: cy + R * Math.sin(angle),
+      rel: ch.relationship ?? 0,
+      sprite: ch.sprite_url || spriteCache[ch.id] || null,
+    };
+  });
+  const nodeMap = Object.fromEntries(nodes.map(n => [n.id, n]));
+
+  // Curved NPC↔NPC bond arcs
+  let arcs = "";
+  // group bonds by pair to detect bidirectional
+  const pairOffset = {};
+  for (const b of bonds) {
+    const key = [b.source_id, b.target_id].sort().join("|");
+    pairOffset[key] = (pairOffset[key] || 0) + 1;
+  }
+  const pairUsed = {};
+  for (const b of bonds) {
+    const src = nodeMap[b.source_id], tgt = nodeMap[b.target_id];
+    if (!src || !tgt) continue;
+    const pairKey = [b.source_id, b.target_id].sort().join("|");
+    const side = (pairOffset[pairKey] > 1 && (pairUsed[pairKey] || 0) === 0) ? 1 : -1;
+    pairUsed[pairKey] = (pairUsed[pairKey] || 0) + 1;
+
+    // Perpendicular offset for the bezier control point
+    const dx = tgt.x - src.x, dy = tgt.y - src.y;
+    const len = Math.sqrt(dx * dx + dy * dy) || 1;
+    const curveStrength = pairOffset[pairKey] > 1 ? 36 : 18;
+    const cpx = (src.x + tgt.x) / 2 + (-dy / len) * curveStrength * side;
+    const cpy = (src.y + tgt.y) / 2 + (dx / len) * curveStrength * side;
+
+    const col = _bondColor(b.note, b.value);
+    const op = (0.35 + Math.abs(b.value) / 100 * 0.65).toFixed(2);
+    const sw = (1 + Math.abs(b.value) / 100 * 3.5).toFixed(1);
+
+    // Arrowhead at 85% along bezier curve (near target)
+    const markerId = `arr-${b.source_id}-${b.target_id}`.replace(/[^a-z0-9-]/gi,"_");
+    arcs += `<defs><marker id="${markerId}" markerWidth="5" markerHeight="5"
+        refX="4" refY="2.5" orient="auto">
+        <polygon points="0,0 5,2.5 0,5" fill="${col}" fill-opacity="${op}"/>
+      </marker></defs>
+      <path d="M${src.x},${src.y} Q${cpx},${cpy} ${tgt.x},${tgt.y}"
+        fill="none" stroke="${col}" stroke-width="${sw}" stroke-opacity="${op}"
+        stroke-linecap="round" marker-end="url(#${markerId})"/>`;
+
+    if (b.note) {
+      // Label at midpoint of bezier — use paint-order stroke for legible outline
+      const lx = 0.25 * src.x + 0.5 * cpx + 0.25 * tgt.x;
+      const ly = 0.25 * src.y + 0.5 * cpy + 0.25 * tgt.y;
+      arcs += `<text x="${lx}" y="${ly - 3}" text-anchor="middle"
+        font-size="9" fill="${col}"
+        paint-order="stroke" stroke="rgba(10,8,18,.85)" stroke-width="3" stroke-linejoin="round"
+        font-family="Georgia,serif" font-style="italic">${b.note}</text>`;
+    }
+  }
+
+  // NPC circle nodes (sprite or emoji) + name coloured by player relation
+  let nodesSvg = "";
+  for (const n of nodes) {
+    const clipId = `cl_${n.id}`.replace(/[^a-z0-9_]/gi,"_");
+    // Border colour by relation to player
+    const borderCol = n.rel > 20 ? "#7ec8a0" : n.rel < -20 ? "#c87e7e" : "rgba(232,193,114,.55)";
+    const nameCol   = n.rel > 20 ? "#9ddcba" : n.rel < -20 ? "#dba0a0" : "rgba(232,193,114,.92)";
+    nodesSvg += `<circle cx="${n.x}" cy="${n.y}" r="22"
+        fill="rgba(255,255,255,.05)" stroke="${borderCol}" stroke-width="1.8"/>`;
+    if (n.sprite) {
+      nodesSvg += `<clipPath id="${clipId}"><circle cx="${n.x}" cy="${n.y}" r="20"/></clipPath>
+        <image href="${n.sprite}" x="${n.x-20}" y="${n.y-20}" width="40" height="40"
+          clip-path="url(#${clipId})" preserveAspectRatio="xMidYMid slice"/>`;
+    } else {
+      nodesSvg += `<text x="${n.x}" y="${n.y+5}" text-anchor="middle" font-size="16">👤</text>`;
+    }
+    // Name label with dark stroke outline for readability
+    nodesSvg += `<text x="${n.x}" y="${n.y+38}" text-anchor="middle"
+        font-size="10.5" fill="${nameCol}" font-family="Georgia,serif"
+        paint-order="stroke" stroke="rgba(10,8,18,.9)" stroke-width="3.5" stroke-linejoin="round">${n.name}</text>`;
+  }
+
+  return `<svg viewBox="0 0 ${W} ${H}" xmlns="http://www.w3.org/2000/svg">
+    ${arcs}${nodesSvg}
+  </svg>`;
 }
 
 // keep track of who's currently on stage for the relations panel
@@ -596,15 +864,16 @@ let lastBg = null;
 function render(v){
   if (v.known_characters?.length) {
     knownChars = v.known_characters;
-    // cache sprite URLs so they survive when chars go off-stage
     for (const ch of knownChars) {
       if (ch.sprite_url) spriteCache[ch.id] = ch.sprite_url;
     }
   }
+  if (v.npc_bonds !== undefined) npcBonds = v.npc_bonds || [];
   $("place").textContent = v.place || "";
   $("speaker").textContent = v.speaker || "";
   typeOut($("line"), v.dialogue || "");
   playTTS(v.audio_b64);
+  if (v.current_music) switchMusic(v.current_music);
   if (v.backdrop_url && v.backdrop_url !== lastBg){
     const bg = $("backdrop");
     bg.classList.remove("on");
@@ -763,17 +1032,11 @@ function busy(state){
   document.querySelectorAll(".target-chip").forEach(b => b.disabled = state);
 }
 
-// --- TTS toggle ---
+// --- TTS toggle + volume ---
+let ttsVol = 1.0;      // 0–1, controlled by settings slider
 let ttsEnabled = true;
-const ttsBtn = $("tts-toggle");
-ttsBtn.textContent = "🔊";
-ttsBtn.classList.add("active");
-ttsBtn.addEventListener("click", () => {
-  ttsEnabled = !ttsEnabled;
-  ttsBtn.textContent = ttsEnabled ? "🔊" : "🔇";
-  ttsBtn.classList.toggle("active", ttsEnabled);
-  if (!ttsEnabled) { const a = $("vn-audio"); if (a) { a.pause(); a.src = ""; } }
-});
+// ttsBtn removed from DOM — state managed solely via settings sliders
+const ttsBtn = { textContent: "", classList: { add:()=>{}, toggle:()=>{}, remove:()=>{} } };
 
 function playTTS(audio_b64) {
   if (!ttsEnabled || !audio_b64) return;
@@ -783,8 +1046,90 @@ function playTTS(audio_b64) {
     audio.id = "vn-audio";
     document.body.appendChild(audio);
   }
+  audio.volume = ttsVol;
   audio.src = audio_b64;
-  audio.play().catch(() => {});  // swallow autoplay policy errors silently
+  audio.play().catch(() => {});
+}
+
+// --- BGM (background music) ---
+const BGM_TRACKS = {
+  calm:     "/music/calm.mp3",
+  romantic: "/music/romantic.mp3",
+  dramatic: "/music/dramatic.mp3",
+  mystery:  "/music/mystery.mp3",
+  sad:      "/music/sad.mp3",
+  joyful:   "/music/joyful.mp3",
+};
+let bgmMasterVolume = 0.35;     // master volume (0–1) — controlled by settings slider
+const BGM_FADE_OUT_MS = 2800;   // old track fades out over this long
+const BGM_FADE_IN_MS  = 3200;   // new track fades in over this long
+const BGM_OVERLAP_MS  = 1200;   // new track starts this many ms before old finishes
+
+let bgmEnabled = true;
+let bgmCurrent = null;   // currently playing Audio object
+let bgmTrackName = null; // track key of bgmCurrent
+
+// bgmBtn removed from DOM — state managed solely via settings sliders
+const bgmBtn = { textContent: "", classList: { add:()=>{}, toggle:()=>{}, remove:()=>{} } };
+
+function switchMusic(name) {
+  if (!name || !BGM_TRACKS[name]) return;
+  if (name === bgmTrackName) return;
+  if (!bgmEnabled) { bgmTrackName = name; return; }
+  _bgmPlay(name);
+}
+
+function _bgmPlay(name) {
+  const old = bgmCurrent;
+  bgmTrackName = name;
+
+  const a = new Audio(BGM_TRACKS[name]);
+  a.loop = true;
+  a.volume = 0;
+  bgmCurrent = a;
+
+  // Helper: actually start the audio and fade it in
+  const startFadeIn = () => {
+    const p = a.play();
+    if (p !== undefined) {
+      p.catch(() => {
+        // Autoplay still blocked — retry on the very next user interaction
+        const retry = () => {
+          if (bgmCurrent === a && bgmEnabled) {
+            a.play().then(() => _bgmFade(a, 0, bgmMasterVolume, BGM_FADE_IN_MS)).catch(() => {});
+          }
+        };
+        document.addEventListener("click",   retry, { once: true });
+        document.addEventListener("keydown", retry, { once: true });
+      });
+    }
+    _bgmFade(a, 0, bgmMasterVolume, BGM_FADE_IN_MS);
+  };
+
+  if (old) {
+    _bgmFade(old, old.volume, 0, BGM_FADE_OUT_MS, () => { old.pause(); old.src = ""; });
+    setTimeout(startFadeIn, BGM_FADE_OUT_MS - BGM_OVERLAP_MS);
+  } else {
+    startFadeIn();
+  }
+}
+
+// Smooth volume ramp using requestAnimationFrame + ease-in-out curve
+function _bgmFade(audio, fromVol, toVol, ms, onDone) {
+  const start = performance.now();
+  function tick(now) {
+    const raw = Math.min(1, (now - start) / ms);
+    // ease-in-out: smoothstep
+    const t = raw * raw * (3 - 2 * raw);
+    audio.volume = fromVol + (toVol - fromVol) * t;
+    if (raw < 1) {
+      requestAnimationFrame(tick);
+    } else {
+      audio.volume = toVol;
+      if (onDone) onDone();
+    }
+  }
+  requestAnimationFrame(tick);
 }
 
 // --- book overlay dismiss ---
@@ -803,12 +1148,17 @@ $("load-file-input").addEventListener("change", async (e) => {
   const file = e.target.files[0];
   if (!file) return;
   const text = await file.text();
+
+  // Start a neutral track NOW (user gesture from the file picker is still active)
+  if (bgmEnabled) switchMusic("calm");
+
   busy(true);
   try {
     // Extract client-side journal history before sending state to server
     let parsed;
     try { parsed = JSON.parse(text); } catch { parsed = {}; }
     const savedHistory = Array.isArray(parsed.journal_history) ? parsed.journal_history : [];
+    const savedAudio   = parsed.audio_settings || null;
 
     const { data } = await client.predict("/load_file", { data: text });
     $("choice-screen").classList.add("hidden");
@@ -818,49 +1168,218 @@ $("load-file-input").addEventListener("change", async (e) => {
     history = savedHistory;
     journalTurn = savedHistory.length > 0 ? savedHistory[savedHistory.length - 1].turn : 0;
 
-    render(data[0]);
+    // Restore audio settings if present
+    if (savedAudio) {
+      const bgmPct = Math.max(0, Math.min(100, savedAudio.bgm_vol ?? 35));
+      const ttsPct = Math.max(0, Math.min(100, savedAudio.tts_vol ?? 100));
+      bgmMasterVolume = bgmPct / 100;
+      ttsVol          = ttsPct / 100;
+      bgmEnabled      = bgmPct > 0;
+      ttsEnabled      = ttsPct > 0;
+      bgmVolSlider.value  = bgmPct;
+      bgmVolVal.textContent  = bgmPct + "%";
+      ttsVolSlider.value  = ttsPct;
+      ttsVolVal.textContent  = ttsPct + "%";
+      if (bgmCurrent) bgmCurrent.volume = bgmMasterVolume;
+      // If there's an explicit saved track and music is enabled, pre-seed the track name
+      // so render()'s switchMusic call (via current_music in ViewState) resumes it.
+      if (savedAudio.bgm_track && bgmEnabled) bgmTrackName = null; // force switchMusic to not skip
+    }
+
+    render(data[0]);  // will call switchMusic with current_music from saved GameState flags
+    // Fallback: if ViewState had no current_music but we saved a track, start it now
+    if (savedAudio?.bgm_track && bgmEnabled && !bgmTrackName) {
+      switchMusic(savedAudio.bgm_track);
+    }
     $("journal-btn").classList.remove("hidden");
-    $("download-save-btn").classList.remove("hidden");
+    $("settings-btn").classList.remove("hidden");
   } catch(err) { alert("Could not load save: " + (err?.message || err)); }
   busy(false);
 });
 
-// --- download save ---
-$("download-save-btn").addEventListener("click", async () => {
+// --- settings panel ---
+$("settings-btn").addEventListener("click", () => $("settings-overlay").classList.add("open"));
+$("settings-close").addEventListener("click", () => $("settings-overlay").classList.remove("open"));
+$("settings-overlay").addEventListener("click", e => {
+  if (e.target === $("settings-overlay")) $("settings-overlay").classList.remove("open");
+});
+
+// --- BGM volume slider ---
+// Moving slider: adjusts master volume live; going to 0 mutes, above 0 unmutes.
+const bgmVolSlider = $("bgm-vol-slider");
+const bgmVolVal    = $("bgm-vol-val");
+bgmVolSlider.addEventListener("input", () => {
+  const pct = parseInt(bgmVolSlider.value, 10);
+  bgmVolVal.textContent = pct + "%";
+  bgmMasterVolume = pct / 100;
+  if (pct === 0) {
+    if (bgmEnabled) {           // mute: fade out & disable
+      bgmEnabled = false;
+      if (bgmCurrent) {
+        _bgmFade(bgmCurrent, bgmCurrent.volume, 0, 500, () => { bgmCurrent.pause(); bgmCurrent.src = ""; });
+        bgmCurrent = null;
+      }
+    }
+  } else {
+    if (!bgmEnabled) {          // unmute: re-enable and restart remembered track
+      bgmEnabled = true;
+      if (bgmTrackName) _bgmPlay(bgmTrackName);
+    } else if (bgmCurrent) {    // just change live volume
+      bgmCurrent.volume = bgmMasterVolume;
+    }
+  }
+  bgmBtn.classList.toggle("active", bgmEnabled);
+  bgmBtn.textContent = bgmEnabled ? "🎵" : "🔇";
+});
+
+// --- TTS volume slider ---
+const ttsVolSlider = $("tts-vol-slider");
+const ttsVolVal    = $("tts-vol-val");
+ttsVolSlider.addEventListener("input", () => {
+  const pct = parseInt(ttsVolSlider.value, 10);
+  ttsVolVal.textContent = pct + "%";
+  ttsVol = pct / 100;
+  ttsEnabled = pct > 0;
+  const a = $("vn-audio"); if (a) a.volume = ttsVol;
+  ttsBtn.classList.toggle("active", ttsEnabled);
+  ttsBtn.textContent = ttsEnabled ? "🔊" : "🔇";
+});
+
+// Save button
+$("settings-save-btn").addEventListener("click", async () => {
+  const btn = $("settings-save-btn");
+  btn.disabled = true;
+  btn.textContent = "Saving…";
   try {
     const { data } = await client.predict("/save_data", {});
-    // Embed the client-side journal history into the save file
     const saveObj = JSON.parse(data[0].json);
     saveObj.journal_history = history;
+    saveObj.audio_settings = {
+      bgm_vol:   Math.round(bgmMasterVolume * 100),
+      tts_vol:   Math.round(ttsVol * 100),
+      bgm_track: bgmTrackName || null,
+    };
     const blob = new Blob([JSON.stringify(saveObj)], { type: "application/json" });
     const a = document.createElement("a");
     a.href = URL.createObjectURL(blob);
     a.download = "ephemeral-hearts-save.json";
     a.click();
     URL.revokeObjectURL(a.href);
-  } catch(err) { console.error("download failed", err); }
+    btn.textContent = "✓ Saved!";
+    setTimeout(() => { btn.textContent = "💾 Save current game"; btn.disabled = false; }, 2000);
+  } catch(err) {
+    console.error("save failed", err);
+    btn.textContent = "⚠️ Failed";
+    setTimeout(() => { btn.textContent = "💾 Save current game"; btn.disabled = false; }, 2000);
+  }
 });
 
+// tone -> initial BGM track (mirrors engine.py start() logic)
+const TONE_MUSIC = { romantic:"romantic", flirty:"romantic", dramatic:"dramatic", bittersweet:"sad", comedic:"joyful" };
+
 // --- start ---
 $("enter").addEventListener("click", async () => {
   const btn = $("enter");
   btn.disabled = true;
   const orig = btn.textContent;
   btn.textContent = "✨ Creating your story…";
+
+  // Kick off music NOW while the user gesture is still fresh.
+  if (bgmEnabled) switchMusic(TONE_MUSIC[$("tone").value] || "calm");
+
+  // --- two-phase segmented progress ---
+  const spEl = $("start-progress");
+  spEl.style.display = "block";
+
+  // Per-phase helpers
+  let _spTick = null;
+  const _spNote = (id, msg) => {
+    const el = $(id);
+    el.style.opacity = "0";
+    setTimeout(() => { el.textContent = msg; el.style.opacity = "1"; }, 200);
+  };
+  // Animate fill toward `target` (0-100) at `stepMs` per tick; resolves when target hit
+  const _spCrawl = (fillId, pctId, target, stepMs) => new Promise(resolve => {
+    if (_spTick) { clearInterval(_spTick); _spTick = null; }
+    const fill = $(fillId), pctEl = $(pctId);
+    let cur = parseFloat(fill.style.width) || 0;
+    _spTick = setInterval(() => {
+      cur = Math.min(target, cur + 0.7);
+      fill.style.width  = cur + "%";
+      pctEl.textContent = Math.round(cur) + "%";
+      if (cur >= target) { clearInterval(_spTick); _spTick = null; resolve(); }
+    }, stepMs);
+  });
+  const _spFinish = (fillId, pctId, label) => {
+    if (_spTick) { clearInterval(_spTick); _spTick = null; }
+    $(fillId).style.width = "100%";
+    $(pctId).textContent  = label || "100%";
+  };
+  const spHide = () => {
+    spEl.style.display = "none";
+    ["sp-fill-llm","sp-fill-img"].forEach(id => { $(id).style.width = "0%"; });
+  };
+
+  // LLM notes cycling (reassuring messages while waiting for the model)
+  const LLM_NOTES = [
+    "The AI is generating your opening scene…",
+    "First load can take 30–60 s while the model warms up…",
+    "Inventing characters, secrets, and a first line just for you…",
+    "Almost done writing — hang on…",
+  ];
+  let _llmNoteIdx = 0;
+  const _llmNoteTick = setInterval(() => {
+    _llmNoteIdx = (_llmNoteIdx + 1) % LLM_NOTES.length;
+    _spNote("sp-note-llm", LLM_NOTES[_llmNoteIdx]);
+  }, 9000);
+
   try {
-    const { data } = await client.predict("/start", { theme: $("theme").value, tone: $("tone").value });
+    // ── Phase 1 : LLM world init ──────────────────────────────────────────
+    _spNote("sp-note-llm", LLM_NOTES[0]);
+    // Crawl 0→88% slowly — will stop there until the real call returns
+    _spCrawl("sp-fill-llm", "sp-pct-llm", 88, 800);
+
+    const { data: d1 } = await client.predict("/start_text", {
+      theme: $("theme").value,
+      tone:  $("tone").value,
+    });
+
+    // LLM done — complete bar 1, unlock bar 2 (stay on setup screen)
+    clearInterval(_llmNoteTick);
+    _spFinish("sp-fill-llm", "sp-pct-llm", "100%");
+    _spNote("sp-note-llm", "Story written ✓");
+    $("sp-step-img").style.opacity = "1";
+    _spNote("sp-note-img", "Generating backdrop and character illustration…");
+    $("sp-pct-img").textContent = "0%";
+
+    // ── Phase 2 : image generation ────────────────────────────────────────
+    // Crawl 0→85% while painter works
+    _spCrawl("sp-fill-img", "sp-pct-img", 85, 350);
+
+    const { data: d2 } = await client.predict("/start_images", {});
+
+    // Everything ready — complete bar 2, then reveal the game
+    _spFinish("sp-fill-img", "sp-pct-img", "100%");
+    _spNote("sp-note-img", "Scene ready ✓");
+    render(d2[0]);
+    addToHistory("", d2[0]);
     $("setup").classList.add("hidden");
-    render(data[0]);
-    addToHistory("", data[0]);
     $("journal-btn").classList.remove("hidden");
-    $("download-save-btn").classList.remove("hidden");
-    // Show the book intro overlay if the engine sent an intro text
-    if (data[0]?.intro_text) {
-      $("book-text").textContent = data[0].intro_text;
-      $("intro-book").classList.remove("hidden");
-    }
+    $("settings-btn").classList.remove("hidden");
+
+    setTimeout(() => {
+      spHide();
+      if (d2[0]?.intro_text) {
+        $("book-text").textContent = d2[0].intro_text;
+        $("intro-book").classList.remove("hidden");
+      }
+    }, 700);
+
   } catch(err) {
     console.error("start failed", err);
+    clearInterval(_llmNoteTick);
+    if (_spTick) { clearInterval(_spTick); _spTick = null; }
+    spHide();
     btn.textContent = "⚠️ Failed — try again";
     btn.disabled = false;
     setTimeout(() => { btn.textContent = orig; }, 3000);

frontend/music/README.md

@@ -0,0 +1,32 @@
+# Background Music Tracks
+
+Place looping MP3 (or OGG) files here. The game expects these exact filenames:
+
+| File | When it plays |
+|---|---|
+| `calm.mp3` | Peaceful moments, exploration, default opening |
+| `romantic.mp3` | Soft intimate scenes, growing closeness |
+| `dramatic.mp3` | Tense confrontations, high stakes |
+| `mystery.mp3` | Uncanny atmosphere, secrets revealed |
+| `sad.mp3` | Melancholic, bittersweet, loss |
+| `joyful.mp3` | Playful, comedic, happy scenes |
+
+## Free sources (royalty-free, loop-friendly)
+
+- **Kevin MacLeod** — https://incompetech.filmmusic.io (CC BY 4.0)
+- **Pixabay Music** — https://pixabay.com/music/ (free, no attribution needed)
+- **FreeMusicArchive** — https://freemusicarchive.org
+
+## Recommended Kevin MacLeod tracks
+
+| Mood | Track name |
+|---|---|
+| calm | "Comfortable Mystery" or "Floating Cities" |
+| romantic | "Sneaky Snitch" or "Heartwarming" |
+| dramatic | "Darkest Child" or "Cipher" |
+| mystery | "Ossuary 5 - Rest" or "Scheming Weasel" |
+| sad | "Sonatina in C Minor" or "Parting of the Ways" |
+| joyful | "Carefree" or "Fluffing a Duck" |
+
+Files must be served from this folder — the app mounts `/music` → `frontend/music/`.
+If a file is missing the browser simply plays nothing for that mood (no crash).

visualnovel/characters.py

@@ -36,6 +36,16 @@ def present_sheets_block(state: GameState) -> str:
             rel_note = "  — barely acquainted; unsolicited touch or flirt feels uncomfortable (negative delta)"
         else:
             rel_note = ""
+        # NPC↔NPC bonds — only mention others who are in the cast
+        npc_bond_lines: list[str] = []
+        for other_id, bond_val in c.npc_relations.items():
+            if other_id in state.characters:
+                other = state.characters[other_id]
+                note = c.npc_relation_notes.get(other_id, "")
+                label = f" ({note})" if note else ""
+                npc_bond_lines.append(f"{other.name}: {bond_val:+d}{label}")
+        npc_bonds_str = "; ".join(npc_bond_lines) if npc_bond_lines else "—"
+
         blocks.append(
             f"### {c.name}  (id: {c.id})\n"
             f"- one_line: {c.one_line}\n"
@@ -43,6 +53,7 @@ def present_sheets_block(state: GameState) -> str:
             f"- voice: {c.voice or '—'}\n"
             f"- goal: {c.goals or '—'}\n"
             f"- mood: {c.mood} | feeling toward wanderer: {rel}/100{rel_note}\n"
+            f"- bonds with others: {npc_bonds_str}\n"
             f"- knows: {facts}"
         )
     return "\n\n".join(blocks) if blocks else "(no spirits on stage — the narrator may speak)"

visualnovel/engine.py

@@ -23,7 +23,7 @@ from . import config, memory, orchestrator, state
 from .llm import get_llm
 from .metrics import collector
 from .painter import get_painter
-from .schemas import DirectorOutput, GameState, SetupForm, SpritePresence, Turn, ViewState
+from .schemas import DirectorOutput, GameState, NPCBond, SetupForm, SpritePresence, Turn, ViewState
 from .stt import get_stt
 from .trace import Tracer
 from .tts import get_tts
@@ -37,10 +37,24 @@ class Engine:
         self.tts = get_tts()
         self.tracer = Tracer(config.TRACE_PATH)
         self.state: GameState | None = None
+        self._pending_out: DirectorOutput | None = None
+        self._pending_intro: str = ""
 
     # -- lifecycle --
     def start(self, setup: SetupForm) -> ViewState:
+        """Full start (used by smoke test / MVP UI). Calls both phases."""
+        self.start_text(setup)
+        return self.start_images()
+
+    def start_text(self, setup: SetupForm) -> ViewState:
+        """Phase 1 — LLM world-init only. Fast. Returns a text-only ViewState (no images/TTS).
+        Sets self.state and stores the opening DirectorOutput for start_images()."""
         self.state, opening = orchestrator.init_world(self.llm, setup)
+        _tone_music: dict[str, str] = {
+            "romantic": "romantic", "flirty": "romantic",
+            "dramatic": "dramatic", "bittersweet": "sad", "comedic": "joyful",
+        }
+        self.state.flags["current_music"] = _tone_music.get(setup.tone, "calm")
         self.state.recent_turns.append(
             Turn(
                 player="(arrives)",
@@ -49,11 +63,47 @@ class Engine:
                 emotion=opening.emotion,
             )
         )
-        state.apply_directives(self.state, opening)  # sets the speaker's mood
+        state.apply_directives(self.state, opening)
         state.save_memory(self.state)
         self.tracer.log(event="start", setup=setup.model_dump(), opening=opening.model_dump())
         intro = self.state.flags.get("situation_intro", "")
-        return self._view(opening, intro_text=intro)
+        # Stash for start_images()
+        self._pending_out: DirectorOutput | None = opening
+        self._pending_intro: str = intro
+        # Build a text-only ViewState so the frontend can show dialogue immediately
+        s = self.state
+        speaker_ch = s.characters.get(opening.speaker)
+        speaker_name = speaker_ch.name if speaker_ch else "The wood"
+        known: list[SpritePresence] = []
+        for cid, ch in s.characters.items():
+            disc = [ch.traits[i] for i in ch.discovered_traits if i < len(ch.traits)]
+            known.append(SpritePresence(
+                id=ch.id, name=ch.name, mood=ch.mood, sprite_url=None,
+                relationship=ch.relationship, public_bio=ch.one_line,
+                discovered_traits=disc, total_traits=len(ch.traits),
+                secret_goal=ch.goals if ch.goal_unlocked else None,
+            ))
+        return ViewState(
+            speaker=speaker_name,
+            dialogue=opening.dialogue,
+            emotion=opening.emotion,
+            place=s.scene.place,
+            backdrop_url=None,
+            present=[],
+            known_characters=known,
+            beat=s.beat,
+            turn_index=s.turn_index,
+            intro_text=intro,
+            current_music=s.flags.get("current_music"),
+            npc_bonds=[],
+        )
+
+    def start_images(self) -> ViewState:
+        """Phase 2 — paint backdrop + sprite, TTS. Call after start_text().
+        Returns the full ViewState."""
+        assert self.state is not None and self._pending_out is not None, \
+            "call start_text() first"
+        return self._view(self._pending_out, intro_text=self._pending_intro)
 
     def transcribe(self, audio_path: str) -> str:
         return self.stt.transcribe(audio_path)
@@ -195,6 +245,19 @@ class Engine:
                 )
             )
 
+        # Collect all directed NPC↔NPC bonds for the frontend graph
+        npc_bonds: list[NPCBond] = []
+        for cid, ch in s.characters.items():
+            for other_id, val in ch.npc_relations.items():
+                if other_id in s.characters:
+                    other = s.characters[other_id]
+                    npc_bonds.append(NPCBond(
+                        source_id=cid, source_name=ch.name,
+                        target_id=other_id, target_name=other.name,
+                        value=val,
+                        note=ch.npc_relation_notes.get(other_id, ""),
+                    ))
+
         speaker_ch = s.characters.get(out.speaker)
         speaker_name = speaker_ch.name if speaker_ch else "The wood"
 
@@ -222,6 +285,8 @@ class Engine:
             notifications=notifications or [],
             intro_text=intro_text,
             audio_b64=audio_b64,
+            current_music=s.flags.get("current_music"),
+            npc_bonds=npc_bonds,
         )
 
 

visualnovel/llm.py

@@ -20,6 +20,11 @@ import sys
 from collections.abc import Generator
 from typing import Any, Protocol
 
+
+def _safe_print(msg: str) -> None:
+    """Print to stdout, replacing unencodable chars (cp1252 on Windows terminals)."""
+    print(msg.encode(sys.stdout.encoding or "utf-8", errors="replace").decode(sys.stdout.encoding or "utf-8", errors="replace"))
+
 from . import config
 
 
@@ -143,13 +148,13 @@ class ModalLLM:
 
     def complete(self, messages: list[dict[str, str]], **kw: Any) -> str:
         result = self._backend.complete.remote(messages, **kw)
-        print(f"[ModalLLM] complete -> {result[:120]!r}")
+        _safe_print(f"[ModalLLM] complete -> {result[:120]!r}")
         return result
 
     def complete_json(self, messages: list[dict[str, str]], schema: dict, **kw: Any) -> dict:
-        print(f"[ModalLLM] complete_json input messages:\n{messages}\n")
+        _safe_print(f"[ModalLLM] complete_json input messages:\n{messages}\n")
         result = self._backend.complete_json.remote(messages, schema, **kw)
-        print(f"[ModalLLM] complete_json -> {result}")
+        _safe_print(f"[ModalLLM] complete_json -> {result}")
         return result
 
 

visualnovel/memory.py

@@ -34,8 +34,17 @@ def assemble_context(state: GameState, player_input: str) -> str:
     if off_stage:
         parts.append("KNOWN BUT OFF STAGE (can return — use their existing id):\n" + "\n".join(off_stage))
 
-    if state.flags:
-        parts.append("FACTS: " + ", ".join(f"{k}={v}" for k, v in state.flags.items()))
+    # Surface the current music track prominently so the LLM doesn't switch it needlessly.
+    current_music = state.flags.get("current_music")
+    if current_music:
+        parts.append(
+            f"CURRENT BGM: \"{current_music}\" — leave set_music null unless a MAJOR tonal "
+            f"shift justifies a change (max once every 6-8 turns)."
+        )
+
+    other_flags = {k: v for k, v in state.flags.items() if k != "current_music"}
+    if other_flags:
+        parts.append("FACTS: " + ", ".join(f"{k}={v}" for k, v in other_flags.items()))
 
     recent = state.recent_turns[-config.RECENT_TURNS_K :]
     if recent:

visualnovel/prompts.py

@@ -43,11 +43,22 @@ Rules:
   - Relationship_delta ranges from -100 to +100. Romantic warmth builds it up; coldness,
     insults, or rejection bring it down. React authentically to negative moments — hurt, cold,
     quietly withdrawing. Do NOT loop the same response — escalate or shift the dynamic.
-  - If a character's relationship reaches -100 → they have had enough. They storm off,
+  - If a character's relationship reaches -100 -> they have had enough. They storm off,
     say something final and cutting, and MUST emit exit_character. They will NOT return
     unless the story calls for a dramatic reconciliation arc.
   - If a character explicitly says goodbye, storms off, or leaves for good -> emit
     exit_character with their exact id to remove them from the stage.
+  - NPCs have their own bonds with each other (shown in "bonds with others" on each sheet).
+    These bonds drive their behaviour: rivals bicker and compete for the player's attention;
+    friends cover for each other and share knowing glances; a jealous NPC makes cutting
+    remarks when another gets too close to the player.
+    Update bonds via npc_relation_deltas when a meaningful interaction shifts the dynamic —
+    e.g. player flirts with A while B watches (B gains jealousy toward A: delta -10 to -20);
+    two NPCs have a warm exchange (delta +10 to +20, note "camaraderie");
+    an NPC defends another from the player's rudeness (delta +15, note "protects").
+    Keep notes short (one word or phrase): "jealousy", "rivalry", "camaraderie",
+    "fondness", "protects", "admires", "resents", "envies", "loyal to".
+    Only update bonds when something actually happens — not every turn.
   - With multiple characters on stage, they may react to each other (banter, jealousy, a
     knowing glance) — but never more than 2 NPC-to-NPC exchanges in a row. After that the
     next line MUST address the player directly.
@@ -55,6 +66,19 @@ Rules:
     established fact.
   - NEVER repeat a line of dialogue verbatim from the recent exchanges. Every response must
     move the scene forward — emotionally, narratively, or tonally.
+  - Music: think of it like a film score — one track covers an entire scene or arc.
+    Use set_music ONLY for major tonal ruptures (a sudden revelation, a scene that flips
+    from lighthearted to tense, a heartbreak, a triumphant moment). As a rule:
+    never switch more than once every 6-8 turns, never two switches in a row,
+    and NEVER switch just because the dialogue shifted slightly in mood.
+    Leave set_music as null on the vast majority of turns.
+    Available tracks (use the exact key string):
+      "calm"     — peaceful ambiance, everyday moments, unhurried exploration
+      "romantic" — soft and intimate, growing closeness, tender confessions
+      "dramatic" — tense confrontations, high stakes, arguments, shock, revelations
+      "mystery"  — uncanny atmosphere, secrets surfacing, strange occurrences
+      "sad"      — melancholy, loss, a bittersweet farewell
+      "joyful"   — playful, comedic, carefree, warm laughter
   - Output MUST be a single JSON object matching the schema. Nothing else.
 """
 
@@ -105,10 +129,10 @@ _ACTION_HINTS: dict[str, str] = {
     "touch": (
         "*The wanderer gently touches the character. "
         "Check their current relationship value in the character sheet: "
-        "below 20 → touch is UNWANTED, they pull back or react with discomfort/anger "
+        "below 20 -> touch is UNWANTED, they pull back or react with discomfort/anger "
         "(negative relationship_delta); "
-        "20-50 → shy or surprised mixed reaction (small delta either way); "
-        "above 50 → welcomed warmly or with flustering (positive relationship_delta).*"
+        "20-50 -> shy or surprised mixed reaction (small delta either way); "
+        "above 50 -> welcomed warmly or with flustering (positive relationship_delta).*"
     ),
     "give": (
         "*The wanderer offers something to the character — "

visualnovel/schemas.py

@@ -41,6 +41,9 @@ class Character(BaseModel):
     discovered_traits: list[int] = Field(default_factory=list)  # indices of unlocked traits
     goal_unlocked: bool = False
     tts_voice_description: str = ""  # frozen at first introduction; never updated by directives
+    # NPC↔NPC bonds — keyed by other character id, value -100..100
+    npc_relations: dict[str, int] = Field(default_factory=dict)
+    npc_relation_notes: dict[str, str] = Field(default_factory=dict)  # other_id -> latest label
 
 
 class Scene(BaseModel):
@@ -83,6 +86,24 @@ class Ending(BaseModel):
     text: str
 
 
+class NPCRelDelta(BaseModel):
+    """One directed bond update between two NPCs."""
+    source: str   # character id who holds the feeling
+    target: str   # character id the feeling is directed at
+    delta: int    # change to apply (-100..100)
+    note: str = ""  # human label: "jealousy", "camaraderie", "rivalry", "fondness", "protects", …
+
+
+class NPCBond(BaseModel):
+    """A directed NPC↔NPC bond for the frontend graph."""
+    source_id: str
+    source_name: str
+    target_id: str
+    target_name: str
+    value: int    # current -100..100
+    note: str = ""
+
+
 class Directives(BaseModel):
     scene_change: SceneChange | None = None
     new_character: NewCharacter | None = None
@@ -91,6 +112,8 @@ class Directives(BaseModel):
     set_flags: dict[str, str] = Field(default_factory=dict)
     advance_beat: bool = False
     ending: Ending | None = None
+    set_music: str | None = None  # one of: calm | romantic | dramatic | mystery | sad | joyful
+    npc_relation_deltas: list[NPCRelDelta] = Field(default_factory=list)
 
 
 class DirectorOutput(BaseModel):
@@ -168,3 +191,5 @@ class ViewState(BaseModel):
     notifications: list[str] = Field(default_factory=list)  # popup messages this turn
     intro_text: str = ""  # shown once in the book overlay at game start; empty on subsequent turns
     audio_b64: str | None = None  # data:audio/wav;base64,... — absent when TTS is mocked
+    current_music: str | None = None  # active BGM track name (calm|romantic|dramatic|mystery|sad|joyful)
+    npc_bonds: list[NPCBond] = Field(default_factory=list)  # all directed NPC↔NPC bonds

visualnovel/state.py

@@ -14,7 +14,7 @@ import re
 from pathlib import Path
 
 from . import config
-from .schemas import Character, DirectorOutput, GameState, Scene
+from .schemas import Character, DirectorOutput, GameState, NPCRelDelta, Scene
 
 _CLAMP = (-100, 100)
 
@@ -77,6 +77,24 @@ def apply_directives(state: GameState, out: DirectorOutput) -> list[str]:
         state.scene.present.remove(d.exit_character)
         effects.append(f"exit_character:{d.exit_character}")
 
+    # NPC↔NPC bond updates
+    for bond in d.npc_relation_deltas:
+        src, tgt = bond.source, bond.target
+        if src in state.characters and tgt in state.characters:
+            ch = state.characters[src]
+            old_val = ch.npc_relations.get(tgt, 0)
+            new_val = max(_CLAMP[0], min(_CLAMP[1], old_val + bond.delta))
+            ch.npc_relations[tgt] = new_val
+            if bond.note:
+                ch.npc_relation_notes[tgt] = bond.note
+            effects.append(f"npc_bond:{src}:{tgt}:{new_val}")
+
+    # music track switch
+    _VALID_TRACKS = {"calm", "romantic", "dramatic", "mystery", "sad", "joyful"}
+    if d.set_music and d.set_music in _VALID_TRACKS:
+        state.flags["current_music"] = d.set_music
+        effects.append(f"music:{d.set_music}")
+
     # arbitrary world flags
     if d.set_flags:
         state.flags.update(d.set_flags)