/* project-buzzer-data.jsx — "The Buzzer" build descriptor.
   Run a 555 fast enough to hear, tune the note, drive a piezo.
   Sets window.PROJECT_BUILD for projectkit.jsx. Names pk-prefixed (BZ_ for build data). */

const pkOhm = (r) => r >= 1000 ? `${(r / 1000).toFixed(r % 1000 ? 1 : 0)} kΩ` : `${r} Ω`;
const pkFar = (c) => c >= 1e-6 ? `${(c * 1e6).toFixed(c * 1e6 % 1 ? 1 : 0)} µF` : `${(c * 1e9).toFixed(0)} nF`;
const pkHz  = (f) => f >= 1000 ? `${(f / 1000).toFixed(2)} kHz` : `${f.toFixed(0)} Hz`;

const BZ_VB = 9;

const BZ_STAGES = [
  {
    id: "audio", n: 1, schem: "audio", part: "ic555",
    title: "Into the Audible", teaches: "Frequency you can hear",
    tagline: "Blink so fast the on/off becomes a tone.",
    intro: {
      adult: "Speed up the 555 past about 20 cycles a second and the 'blinks' fuse into a pitch your ear hears as a tone. With R1 = 1 kΩ and R2 = 6.8 kΩ, pick the timing capacitor so it lands in the audible band — 300 Hz to 3 kHz, the meat of where small buzzers sing.",
      kids: "If you make the blinking chip go really fast, the on-off turns into a sound you can hear! Pick the timing bucket so it buzzes in the range your ears like best.",
    },
    spec: "Oscillate in the audible band: 300 Hz – 3 kHz.",
    givens: ["R1 = 1 kΩ", "R2 = 6.8 kΩ", "f = 1.44 ÷ ((R1 + 2·R2)·C)", "Ears hear ~20 Hz – 20 kHz"],
    explain: "It's the same 555 astable as a blinker — just fast. f = 1.44 ÷ ((R_1 + 2·R_2)·C). Below ~20 Hz you see flashes; above it, the air pulses fast enough that you hear a tone. A smaller capacitor means a higher pitch.",
    picks: [{
      id: "C", label: "Timing capacitor", unit: "F",
      hint: "Smaller C → higher pitch. Land between 300 Hz and 3 kHz.",
      options: [1e-6, 1e-7, 4.7e-8, 1e-8].map(c => ({ label: pkFar(c), value: c })),
    }],
    check: (v) => {
      const f = 1.44 / ((1000 + 2 * 6800) * v.C);
      const ok = f >= 300 && f <= 3000;
      return {
        ok,
        headline: `Tone ≈ ${pkHz(f)}`,
        formula: `f = 1.44 ÷ ((1 kΩ + 2×6.8 kΩ) × ${pkFar(v.C)}) = ${pkHz(f)}`,
        lines: [{ k: "Target", v: "300 Hz – 3 kHz" }, { k: "Your frequency", v: pkHz(f), ok }],
        note: {
          adult: ok ? "Right in the ear's sweet spot — a clear, present buzz from a small piezo." : f < 300 ? "So low it's more a flutter than a tone — and small buzzers barely move there. Use a smaller capacitor." : "Up into a piercing whistle. Easing back with a bigger capacitor gives a friendlier tone.",
          kids: ok ? "A clear buzz you can really hear!" : f < 300 ? "Too low — more of a flutter. Smaller bucket." : "Super high and piercing — bigger bucket.",
        },
      };
    },
  },
  {
    id: "tune", n: 2, schem: "tune", part: "cap",
    title: "Tune the Note", teaches: "Pitch is frequency",
    tagline: "Set the resistor to land on a real musical note.",
    intro: {
      adult: "Pitch is just frequency. Hold R1 = 1 kΩ and C = 0.1 µF, then pick R2 to land near concert A — 440 Hz, the note an orchestra tunes to. Bigger R2 means a lower note; the relationship is f = 1.44 ÷ ((R1 + 2·R2)·C).",
      kids: "A higher buzz is a higher note. Pick the resistor that lands your buzzer on a real musical note — 'A', the one a whole orchestra tunes to.",
    },
    spec: "Land near concert A: 410 – 470 Hz (target 440 Hz).",
    givens: ["R1 = 1 kΩ", "C = 0.1 µF", "Target ≈ 440 Hz (note A4)", "f = 1.44 ÷ ((R1 + 2·R2)·C)"],
    explain: "Notes are frequencies: A4 is 440 Hz, and each octave doubles it. Tuning the buzzer is just choosing R2 so the 555's frequency lands on the note. Bigger R2 slows the charge and lowers the pitch.",
    picks: [{
      id: "R2", label: "Pitch resistor R2", unit: "Ω",
      hint: "Bigger R2 → lower note. Aim for ~440 Hz.",
      options: [6800, 15000, 33000, 47000].map(r => ({ label: pkOhm(r), value: r })),
    }],
    check: (v) => {
      const f = 1.44 / ((1000 + 2 * v.R2) * 1e-7);
      const ok = f >= 410 && f <= 470;
      return {
        ok,
        headline: `Pitch ≈ ${pkHz(f)}${ok ? " (≈ A4)" : ""}`,
        formula: `f = 1.44 ÷ ((1 kΩ + 2×${pkOhm(v.R2)}) × 0.1 µF) = ${pkHz(f)}`,
        lines: [{ k: "Target", v: "≈ 440 Hz (A4)" }, { k: "Your pitch", v: pkHz(f), ok }],
        note: {
          adult: ok ? "Bang on concert A — 15 kΩ puts it within a couple of Hz of 440. Hum along to check." : f > 470 ? "Sharp — sitting above A. Increase R2 to slow it down to pitch." : "Flat — below A. Decrease R2 to raise the pitch.",
          kids: ok ? "That's the note 'A' — perfectly in tune!" : f > 470 ? "Too high a note — use a bigger resistor." : "Too low a note — use a smaller resistor.",
        },
      };
    },
  },
  {
    id: "out", n: 3, schem: "piezo-out", part: "piezo", final: true,
    title: "Make It Sound", teaches: "Driving a piezo",
    tagline: "Pick an output the 555 can drive on its own.",
    intro: {
      adult: "The 555 output can source about 200 mA — fine for a piezo, which is nearly an open capacitor and sips only a few mA. A low-impedance speaker is a different story: 9 V across 8 Ω would demand over an amp and destroy the chip. Driving straight from the 555 (no extra driver), which output is safe and loud?",
      kids: "The chip can only push so hard. A piezo buzzer barely sips power, so the chip drives it easily and loud. A regular speaker would try to pull way too much and break the chip. Which one can the chip handle by itself?",
    },
    spec: "Drive it straight from the 555 (no extra driver): stay within the chip's ~200 mA limit. This is the finale.",
    givens: ["555 output sources ≈ 200 mA", "Piezo ≈ high-impedance, ~3 mA", "8 Ω speaker: I = 9 V ÷ 8 Ω ≈ 1.1 A", "No extra driver this build"],
    explain: "A piezo behaves like a small capacitor — almost no steady current — so the 555 drives it directly. An 8 Ω speaker pulls I = V ÷ R ≈ 1.1 A, five times the chip's limit; it would need its own transistor, which this minimal build doesn't have.",
    picks: [{
      id: "out", label: "Output device", hint: "Which stays under the 555's 200 mA, driven directly?",
      options: [
        { label: "Piezo buzzer, direct", value: "piezo" },
        { label: "8 Ω speaker, direct", value: "speaker" },
        { label: "8 Ω speaker + transistor", value: "speaker-tx" },
      ],
    }],
    check: (v) => {
      const ok = v.out === "piezo";
      const draw = { piezo: "≈ 3 mA", speaker: "≈ 1.1 A", "speaker-tx": "needs a driver" };
      return {
        ok,
        headline: v.out === "piezo" ? "Piezo · ~3 mA — loud and safe" : v.out === "speaker" ? "Speaker · ~1.1 A — 5× over the limit" : "Speaker + transistor — extra part",
        formula: v.out === "speaker" ? "I = 9 V ÷ 8 Ω ≈ 1.1 A  ≫  200 mA limit" : v.out === "piezo" ? "piezo ≈ open capacitor → ~3 mA  <  200 mA limit" : "valid, but that's no longer 'direct from the 555'",
        lines: [
          { k: "555 source limit", v: "≈ 200 mA" },
          { k: "Your output draws", v: draw[v.out], ok },
        ],
        note: {
          adult: ok ? "Perfect for a minimal build — the piezo sips current, so the 555 drives it directly and loudly. Your buzzer sounds." : v.out === "speaker" ? "An 8 Ω speaker pulls over an amp straight off the chip — instant destruction. Use a piezo here, or add a transistor to drive the speaker." : "That genuinely works — but it adds a transistor, and the spec was to drive directly with the parts in this build. Reach for the piezo.",
          kids: ok ? "The piezo buzzes loud and the chip stays safe — the Buzzer is ALIVE! 🎉" : v.out === "speaker" ? "The speaker pulls way too much and breaks the chip. Use the piezo." : "That works, but needs an extra part. Use the piezo to keep it simple.",
        },
      };
    },
  },
];

window.PROJECT_BUILD = {
  id: "buzzer", name: "The Buzzer", em: "Buzzer", kicker: "Project 05 · sound",
  hero: {
    adult: "Run the blinker fast enough and the blink becomes a pitch. You'll push a 555 up into the audible band, tune it to a real musical note, and drive a piezo straight from the chip — the front half of every synth, alarm, and doorbell, built from a handful of parts.",
    kids: "Make beeps and tones you can actually hear! You'll speed the blinking chip up until it sings, tune it to a real note, and drive a little buzzer so it sounds out loud.",
  },
  stages: BZ_STAGES,
  learned: {
    audio: ["Above ~20 Hz a blink fuses into a tone; the 555 reaches kHz easily.", "f = 1.44 ÷ ((R_1 + 2·R_2)·C) — the same timing formula, just faster."],
    tune:  ["Pitch is frequency: A4 = 440 Hz, and each octave doubles it.", "Bigger timing parts → a lower note."],
    out:   ["A piezo is high-impedance — it sips current, so the 555 drives it directly.", "A low-Ω speaker would over-draw the chip; it needs its own transistor."],
  },
  finale: {
    adult: "Three stages — a tone in the audible band, tuned to concert A, driven from a piezo the chip can handle — and you've built an instrument's front end from a timer and a disc. Sound, from first principles.",
    kids: "You made a real tuned beep from a chip and a buzzer! Speed becomes pitch, and a tiny disc turns it into sound — that's how alarms and doorbells work.",
  },
  bench: {
    adult: "You've specified every value. Wire it on the breadboard in this order — the 555 with its timing parts, the pitch resistor, then the piezo straight off the output:",
    kids: "You have the plan. Build it for real — the timer chip first, then the pitch resistor, then the piezo buzzer on the output.",
  },
  specFoot: "Supply 9 V · 555 astable · A4 = 440 Hz reference · piezo output · every value meets its target spec.",
};