Merge pull request #5 from NeverEndingCode/worktree-v1.6-onboarding-qol

v1.6.0: Onboarding & QoL — a reusable tour framework, heat tunables, Racks fixes

Author: NeverEndingCode

CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## v1.6.0
+
+Onboarding & quality of life: a guided tour for new and existing players,
+plus four fixes to things that were quietly wrong.
+
+- Guided tour: a spotlight walkthrough that dims the screen, highlights the
+  real control it is describing, and steps through the whole rack - racks,
+  Grid, Overclock and heat, upgrades, goals, minigames, Cold Storage, Social,
+  Singularity, Migrate, and a live event if one is running. It is
+  unlock-aware, so a brand-new account sees 11 steps covering only what it
+  can actually reach, and a fully-unlocked account sees all 17. Skip is on
+  every step, and Escape works too.
+- It runs once for existing players as well as new ones, then never again.
+  Replay it any time from Profile -> Settings -> Tutorials.
+- Under the hood this is a tour *framework*, not a single tutorial. Completion
+  is tracked per named tour, so a future release can ship a short tour
+  covering only its new feature and show it to existing players without
+  anyone sitting through the full tutorial a second time. A feature tour's
+  steps are the same array the full tutorial composes, so the copy is only
+  ever written once.
+- The Overheat popup now dismisses itself after 15 seconds instead of waiting
+  for a click. Tunable from the Balancing tab (`heat.overheatPopupMs`); set
+  it to 0 to restore the old click-to-dismiss behaviour.
+- Venting now sheds a **percentage** of your heat capacity rather than a flat
+  amount, so it is no longer quietly weakened by anything that raises
+  capacity - Summer Surge's `heat.capacity: 4000` overlay, or Heat-Sink Tapes.
+  The Vent button and the Overclock explainer both show the live numbers
+  instead of hardcoded ones.
+  **Admin note:** `heat.ventAmount` is replaced by `heat.ventPercent`
+  (default 25). At stock settings this is exactly balance-neutral - 25% of the
+  default 2000 capacity is the 500 it replaced - but if you had tuned
+  `ventAmount` away from 500, that tuning is reset to 25% and will need
+  re-tuning in the Balancing tab.
+- The Racks "Collect" button now stays visible until the tier is automated,
+  greying out when there is nothing banked, instead of vanishing for a moment
+  after every collect.
+- Fixed a literal `·` showing up next to automated racks in the Racks
+  tab.
+
 ## v1.5.0
 
 Social & Retention: a daily contracts board, global leaderboards,

Dockerfile

@@ -38,7 +38,7 @@ ENV DB_PATH=/app/data/rackstack.db
 LABEL org.opencontainers.image.source="https://github.com/NeverEndingCode/rackstack-server"
 LABEL org.opencontainers.image.description="RackStack self-hosted server"
 LABEL org.opencontainers.image.licenses="MIT"
-LABEL org.opencontainers.image.version="1.5.0"
+LABEL org.opencontainers.image.version="1.6.0"
 
 VOLUME ["/app/data"]
 EXPOSE 3000

client/src/RackStack.jsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, useRef, useMemo } from 'react';
+import { useState, useEffect, useRef, useMemo, useCallback } from 'react';
 
 import {
   TICK_MS, ANOMALY_LABELS, EVENT_REFRESH_THROTTLE_MS, CONFIG_POLL_MS,
@@ -8,7 +8,7 @@ import { cardBorder, textDim, textMain, teal, amber, danger, inset } from './gam
 import { TABS } from './game/data/tabs.js';
 import {
   fetchState, fetchConfig, makeActionQueue, startMinigame, finishMinigame,
-  fetchEvent, setLeaderboardOptOut, fetchLeaderboard,
+  fetchEvent, setLeaderboardOptOut, fetchLeaderboard, setTourCompleted,
 } from './game/api.js';
 import { evaluate } from '@shared/state.js';
 import { applyAction, EVENT_CLAIM_GRACE_MS } from '@shared/reducer.js';
@@ -40,6 +40,10 @@ import MatchOverlay from './game/components/minigames/MatchOverlay.jsx';
 import BalanceOverlay from './game/components/minigames/BalanceOverlay.jsx';
 import ModalRoot from './game/components/modals/ModalRoot.jsx';
 import ProfileView from './game/components/profile/ProfileView.jsx';
+import TutorialOverlay from './game/components/TutorialOverlay.jsx';
+import { CLIENT_TOURS } from './game/data/tours/index.js';
+import { selectTour, resolveSteps } from './game/tourSelection.js';
+import { TOURS, TOUR_IDS } from '@shared/tours.js';
 
 /*
   RACKSTACK - idle infrastructure tycoon
@@ -76,6 +80,22 @@ function isEventTabVisible(eventProgress, pendingClaims, now) {
   return Array.isArray(pendingClaims) && pendingClaims.length > 0;
 }
 
+// v1.6: the tour's unlock context. Module scope so the auto-start effect
+// (which must live above RackStack's early return, per the rules of hooks)
+// and the render path below it share ONE definition of "unlocked" and cannot
+// drift apart.
+function buildTourCtx(state, now) {
+  if (!state) return null;
+  return {
+    gridUnlocked: state.run.tiers[2].owned >= 1,
+    overclockUnlocked: state.run.tiers[3].owned >= 1,
+    singularityUnlocked: state.meta.legacyCores >= 50
+      || state.meta.stats.singularities > 0 || state.meta.singularityShards > 0,
+    coldStorageUnlocked: state.run.tiers[4].owned >= 1,   // Server Room
+    eventLive: isEventLive(state.meta.eventProgress, now),
+  };
+}
+
 // Identity of the EFFECTIVE gameplay config. The stored config's `version`
 // alone is not enough: activating or ending a live event changes the numbers
 // the server evaluates with (its modifiers are overlaid on the baseline)
@@ -100,6 +120,16 @@ export default function RackStack({ user }) {
   const [activeTab, setActiveTab] = useState('racks');
   const [minigame, setMinigame] = useState(null);
   const [profileOpen, setProfileOpen] = useState(false);
+  // v1.6 guided tours. `toursCompleted` mirrors users.tours_completed, which
+  // arrives on the `user` prop from App.jsx's /api/me fetch; `activeTour` is
+  // { id, steps } once one is running.
+  const [toursCompleted, setToursCompleted] = useState(
+    () => (Array.isArray(user?.toursCompleted) ? user.toursCompleted : null),
+  );
+  const [activeTour, setActiveTour] = useState(null);
+  // Spec 4.6: after a tour ends, don't auto-start another until the next app
+  // load, so a player is never carpet-bombed with several tours in a row.
+  const tourRanThisLoadRef = useRef(false);
   // Live Events (v1.4): the currently (or most-recently, through grace -
   // see refreshEventData below) active event's identity/ladder, and the
   // opt-out-filtered leaderboard for it. Neither is part of canonical
@@ -946,6 +976,43 @@ export default function RackStack({ user }) {
     setMinigameSynced(null);
   }
 
+  // ---- v1.6 guided tours -------------------------------------------------
+  // These hooks must stay ABOVE the early return below.
+  useEffect(() => {
+    if (!state || !toursCompleted || activeTour || tourRanThisLoadRef.current || modal) return;
+    const ctx = buildTourCtx(state, Date.now());
+    const autoStartById = Object.fromEntries(TOURS.map((t) => [t.id, t.autoStart]));
+    const sel = selectTour(CLIENT_TOURS, TOUR_IDS, toursCompleted, ctx, autoStartById);
+    if (sel) {
+      tourRanThisLoadRef.current = true;
+      setActiveTour(sel);
+    }
+  }, [state, toursCompleted, activeTour, modal]);
+
+  // Finishing and skipping are the same write: a player who skipped made a
+  // choice, and re-showing a dismissed tour is the worse failure mode.
+  // Optimistic - the overlay closes immediately and a failed write only costs
+  // the tour re-offering next load, which beats blocking on the network.
+  const endTour = useCallback((tourId) => {
+    setActiveTour(null);
+    setToursCompleted((cur) => (cur && cur.includes(tourId) ? cur : [...(cur || []), tourId]));
+    setTourCompleted(tourId, true).then((res) => {
+      if (res && Array.isArray(res.toursCompleted)) setToursCompleted(res.toursCompleted);
+    }).catch(() => {});
+  }, []);
+
+  // Profile -> Tutorials -> Replay. Bypasses the once-per-load rule: the
+  // player explicitly asked for it.
+  const startTour = useCallback((tourId) => {
+    const tour = CLIENT_TOURS[tourId];
+    if (!tour || !stateRef.current) return;
+    const steps = resolveSteps(tour, buildTourCtx(stateRef.current, Date.now()));
+    if (steps.length === 0) return;
+    setActiveTour({ id: tourId, steps });
+    setToursCompleted((cur) => (cur || []).filter((id) => id !== tourId));
+    setTourCompleted(tourId, false).catch(() => {});
+  }, []);
+
   if (!loaded || !state || !config) {
     return (
       <div style={{ minHeight: '100vh', background: '#0E141B', color: textDim, display: 'flex', alignItems: 'center', justifyContent: 'center' }} className="font-mono text-sm">
@@ -975,10 +1042,8 @@ export default function RackStack({ user }) {
   const gain = migrateGain(state.run.lifetimeRun, eff.legacyGainMult);
   const singularityGain = Math.floor(Math.sqrt(state.meta.legacyCores || 0));
 
-  const gridUnlocked = state.run.tiers[2].owned >= 1;
-  const overclockUnlocked = state.run.tiers[3].owned >= 1;
-  const singularityUnlocked = state.meta.legacyCores >= 50 || state.meta.stats.singularities > 0 || state.meta.singularityShards > 0;
-  const coldStorageUnlocked = state.run.tiers[4].owned >= 1; // Server Room
+  // Single source of truth with the tour's auto-start effect above.
+  const { gridUnlocked, overclockUnlocked, singularityUnlocked, coldStorageUnlocked } = buildTourCtx(state, now);
   const anyReady = state.run.tiers.some((ts) => !ts.manager && ts.ready > 0.01);
   const anyManualOwned = state.run.tiers.some((ts) => ts.owned > 0 && !ts.manager);
 
@@ -1067,6 +1132,8 @@ export default function RackStack({ user }) {
           heatColor={heatColor}
           onCooldown={heatOnCooldown}
           cooldownSecondsLeft={cooldownSecondsLeft}
+          ventPercent={config.data.heat.ventPercent}
+          overheatCooldownMs={config.data.heat.overheatCooldownMs}
         />
       )}
 
@@ -1182,6 +1249,8 @@ export default function RackStack({ user }) {
           onLogout={logout}
           onOpenReset={() => setModal({ type: 'reset' })}
           onConfigSaved={handleConfigSaved}
+          toursCompleted={toursCompleted || []}
+          onStartTour={(tourId) => { setProfileOpen(false); startTour(tourId); }}
         />
       )}
 
@@ -1194,7 +1263,17 @@ export default function RackStack({ user }) {
         onMigrate={doMigrate}
         onSingularity={doSingularity}
         onHardReset={hardReset}
+        meltdownAutoDismissMs={config.data.heat.overheatPopupMs}
       />
+
+      {activeTour && (
+        <TutorialOverlay
+          steps={activeTour.steps}
+          onStepChange={setActiveTab}
+          onFinish={() => endTour(activeTour.id)}
+          onSkip={() => endTour(activeTour.id)}
+        />
+      )}
     </div>
   );
 }

client/src/game/api.js

@@ -168,6 +168,16 @@ export function setLeaderboardOptOut(optOut) {
   return postJSON('/api/me/leaderboard-opt-out', { optOut }, 'PUT');
 }
 
+// PUT /api/me/tours { tourId, completed } -> { ok, toursCompleted }
+//   | 400 { error: 'invalid_request' }  (unregistered tourId, bad types)
+// `completed: false` is the replay path. Completing 'onboarding' marks every
+// registered tour complete server-side (spec §4.7), so the response's
+// toursCompleted is authoritative - callers should adopt it rather than
+// predicting the new set locally.
+export function setTourCompleted(tourId, completed) {
+  return postJSON('/api/me/tours', { tourId, completed }, 'PUT');
+}
+
 // GET /api/leaderboard -> { generatedAt, boards: { <boardKey>: [row] } }
 //   where row is { userId, username, avatarUrl, value, badges: [achievementId] }
 //

client/src/game/components/ColdStoragePanel.jsx

@@ -41,7 +41,7 @@ export default function ColdStoragePanel({ meta, config, onClaimBlock, onClaimAl
   const jobDone = job && job.accruedOfflineSec >= jobDurSec;
 
   return (
-    <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-3">
+    <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-3" data-tour="coldstorage-track">
       <div className="rounded-lg p-3 flex items-center justify-between" style={{ background: cardBg, border: `1px solid ${cardBorder}` }}>
         <div className="flex items-center gap-2 text-sm font-semibold" style={{ color: textMain }}>
           <CassetteTape size={16} color={teal} /> Tapes

client/src/game/components/EventPanel.jsx

@@ -129,7 +129,7 @@ export default function EventPanel({
 
   if (!hasCurrent) {
     return (
-      <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-3">
+      <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-3" data-tour="event-ladder">
         {pending.map((entry) => (
           <PendingClaimCard key={entry.event.id} entry={entry} onClaim={onClaimRung} />
         ))}
@@ -149,7 +149,7 @@ export default function EventPanel({
   const graceMsLeft = Math.max(0, (eventProgress.endsAt + EVENT_CLAIM_GRACE_MS) - now);
 
   return (
-    <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-3">
+    <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-3" data-tour="event-ladder">
       <div className="rounded-xl p-4" style={{ background: cardBg, border: `1px solid ${accent}` }}>
         <div className="flex items-center gap-2">
           {icon ? <span className="text-2xl leading-none">{icon}</span> : <Trophy size={22} color={accent} />}

client/src/game/components/GamesPanel.jsx

@@ -33,7 +33,7 @@ function GameCard({ Icon, iconColor, title, desc, btnColor, btnTextColor, onPlay
 export default function GamesPanel({ onStartRush, onStartDebug, onStartMatch, onStartBalance, cooldowns, minigamesConfig }) {
   const { rush, debug, match, balance } = minigamesConfig;
   return (
-    <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-3">
+    <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-3" data-tour="games-list">
       <GameCard Icon={Zap} iconColor={amber} title="Overclock Rush" desc={`Tap as fast as you can for ${rush.durationSec} seconds.`} btnColor={amber} btnTextColor="#0E141B" onPlay={onStartRush} cooldownUntil={cooldowns.rush} />
       <GameCard Icon={Bug} iconColor={teal} title="Debug Sprint" desc={`Squash the highlighted bugs before they hide - up to ${debug.maxLit} can appear at once. ${debug.durationSec} seconds.`} btnColor={teal} btnTextColor="#0E141B" onPlay={onStartDebug} cooldownUntil={cooldowns.debug} />
       <GameCard Icon={Cable} iconColor={violet} title="Cable Match" desc={`Find all ${match.pairCount} matching pairs - the round ends the instant you finish. Only a full match pays out. ${match.durationSec} seconds.`} btnColor={violet} btnTextColor="#0E141B" onPlay={onStartMatch} cooldownUntil={cooldowns.match} />

client/src/game/components/GoalsPanel.jsx

@@ -7,7 +7,7 @@ export default function GoalsPanel({ ctx, meta, onClaimGoal, onClaimRepeatable }
   const [showCompleted, setShowCompleted] = useState(false);
   const completedCount = Object.keys(meta.goalsCompleted).length;
   return (
-    <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-2">
+    <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-2" data-tour="goals-list">
       <div className="flex items-center justify-between text-xs font-mono mb-1" style={{ color: textDim }}>
         <span>{completedCount}/{GOAL_DEFS.length} completed</span>
         <button onClick={() => setShowCompleted((s) => !s)} style={{ color: violet }}>{showCompleted ? 'Hide completed' : 'Show completed'}</button>

client/src/game/components/GridPanel.jsx

@@ -4,7 +4,7 @@ import { GRID_DEFS } from '../data/tiers.js';
 
 export default function GridPanel({ run, gridMult, thresholds, onBuy }) {
   return (
-    <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-3">
+    <div className="max-w-2xl mx-auto px-4 py-4 flex flex-col gap-3" data-tour="grid-buy">
       <div className="rounded-lg p-3 text-xs" style={{ background: cardBg, border: `1px solid ${cardBorder}`, color: textDim }}>
         The Grid runs on its own &mdash; no automation needed. Volunteers contribute FLOPS straight to your total, all the time.
       </div>

client/src/game/components/MigrateBar.jsx

@@ -3,7 +3,7 @@ import { amber, cardBg, inset, cardBorder, textDim, textMain } from '../theme.js
 
 export default function MigrateBar({ gain, showCollectAll, collectDisabled, onMigrate, onCollectAll }) {
   return (
-    <div className="mt-3 flex gap-2">
+    <div className="mt-3 flex gap-2" data-tour="migrate-bar">
       <button
         onClick={onMigrate}
         disabled={gain <= 0}