/* Calculation practice engine v1 (docs/SPEC.md 5.1, 24). Plain browser JS, no modules, no network. Exposes window.UnitSimEngine. Worked example step-through, then a drill of randomised rounds: variables are rolled on their min..max step grid, substituted into the template, and the learner types a numeric answer checked against a whitelisted recursive-descent arithmetic parser (numbers, declared variables, + - * / and parentheses only — never eval). Optional game mode: countdown timer, streak bonus, beat-your-best banner via config.personal_best. */ (function () { "use strict"; var STYLE = [ ".cp-header { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin-bottom: 8px; }", ".cp-expr { display: block; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 14.5px; background: #f6f8fc; border: 1px solid #e2e6ef; border-radius: 8px; padding: 8px 10px; margin-top: 6px; overflow-x: auto; white-space: pre; }", ".cp-step { padding: 10px 0; border-bottom: 1px solid #eef1f8; }", ".cp-step:last-child { border-bottom: none; }", ".cp-step-num { display: inline-flex; align-items: center; justify-content: center; min-width: 24px; height: 24px; border-radius: 999px; background: #eef1f8; color: #4c5670; font-size: 12.5px; font-weight: 600; margin-right: 8px; }", ".cp-answer-row { display: flex; align-items: center; gap: 10px; margin: 10px 0; }", ".cp-answer-row .us-input { flex: 1 1 auto; min-width: 0; font-size: 17px; }", ".cp-unit { flex: 0 0 auto; font-weight: 600; color: #4c5670; font-size: 15px; }", ".cp-question { font-size: 16.5px; }", ".cp-hint-list { margin: 0; padding: 0; list-style: none; }", ".cp-hint-list li { border-radius: 10px; border: 1px solid #efe2b4; background: #fdf7e3; color: #6f5713; padding: 10px 12px; margin: 8px 0; font-size: 14.5px; }", ".cp-best-banner { border-radius: 10px; border: 1px solid #c4d4f9; background: #eaf0fe; color: #1d3f8f; padding: 10px 14px; margin: 10px 0; font-size: 14.5px; }", ".cp-best-banner.cp-beaten { border-color: #bfe8d4; background: #ecfaf3; color: #0d5c3d; }", ".cp-streak { display: inline-block; margin-left: 8px; padding: 1px 8px; border-radius: 999px; font-size: 12px; font-weight: 600; background: #ecfaf3; border: 1px solid #bfe8d4; color: #0d5c3d; }", ".cp-meta-row { display: flex; align-items: center; justify-content: space-between; gap: 10px; flex-wrap: wrap; margin-bottom: 6px; }", "@media (max-width: 420px) { .cp-answer-row { gap: 8px; } }" ].join("\n"); // ---- whitelisted expression parser -------------------------------------- // Grammar: expr := term (('+'|'-') term)* ; term := factor (('*'|'/') factor)* // factor := '-' factor | NUMBER | IDENT | '(' expr ')' // Only numbers, declared variable names, + - * / and parentheses. Anything // else raises a parse error which the engine surfaces gracefully. function tokenize(src) { var tokens = []; var i = 0; while (i < src.length) { var c = src.charAt(i); if (c === " " || c === "\t" || c === "\n" || c === "\r") { i++; continue; } if (c === "+" || c === "-" || c === "*" || c === "/" || c === "(" || c === ")") { tokens.push({ type: c }); i++; continue; } var rest = src.slice(i); var num = /^(?:\d+\.?\d*|\.\d+)/.exec(rest); if (num) { tokens.push({ type: "num", value: parseFloat(num[0]) }); i += num[0].length; continue; } var ident = /^[A-Za-z_][A-Za-z0-9_]*/.exec(rest); if (ident) { tokens.push({ type: "var", name: ident[0] }); i += ident[0].length; continue; } throw new Error("Unexpected character \"" + c + "\" in expression"); } return tokens; } function evaluateExpression(src, vars) { var tokens = tokenize(String(src)); var pos = 0; function peek() { return pos < tokens.length ? tokens[pos] : null; } function next() { return tokens[pos++]; } function parseExpr() { var value = parseTerm(); var t = peek(); while (t && (t.type === "+" || t.type === "-")) { next(); var rhs = parseTerm(); value = t.type === "+" ? value + rhs : value - rhs; t = peek(); } return value; } function parseTerm() { var value = parseFactor(); var t = peek(); while (t && (t.type === "*" || t.type === "/")) { next(); var rhs = parseFactor(); value = t.type === "*" ? value * rhs : value / rhs; t = peek(); } return value; } function parseFactor() { var t = peek(); if (!t) throw new Error("Expression ended unexpectedly"); if (t.type === "-") { next(); return -parseFactor(); } if (t.type === "num") { next(); return t.value; } if (t.type === "var") { next(); if (!Object.prototype.hasOwnProperty.call(vars, t.name)) { throw new Error("Unknown name \"" + t.name + "\" in expression"); } return Number(vars[t.name]); } if (t.type === "(") { next(); var inner = parseExpr(); var close = peek(); if (!close || close.type !== ")") throw new Error("Missing closing parenthesis"); next(); return inner; } throw new Error("Unexpected token in expression"); } var result = parseExpr(); if (pos < tokens.length) throw new Error("Unexpected extra input in expression"); return result; } // ---- helpers ------------------------------------------------------------- function el(tag, className, text) { var n = document.createElement(tag); if (className) n.className = className; if (text != null) n.textContent = text; return n; } function decimalsOf(x) { var s = String(x); var e = s.indexOf("e-"); if (e !== -1) return Math.min(8, parseInt(s.slice(e + 2), 10) || 0); var d = s.indexOf("."); return d === -1 ? 0 : Math.min(8, s.length - d - 1); } function fmtNumber(n) { if (!isFinite(n)) return String(n); var r = Math.round(n * 1e6) / 1e6; return String(r); } function rollValue(v) { var min = Number(v.min); var max = Number(v.max); var step = Number(v.step) > 0 ? Number(v.step) : 1; if (!isFinite(min)) min = 0; if (!isFinite(max) || max < min) max = min; var slots = Math.max(0, Math.floor((max - min) / step + 1e-9)); var k = Math.floor(Math.random() * (slots + 1)); var dec = Math.max(decimalsOf(step), decimalsOf(min)); var value = min + k * step; var pow = Math.pow(10, dec); return Math.round(value * pow) / pow; } function substituteTemplate(template, values) { return String(template).replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, function (m, name) { return Object.prototype.hasOwnProperty.call(values, name) ? fmtNumber(values[name]) : m; }); } // ---- engine -------------------------------------------------------------- function mountInner(rootEl, content, SimSDK, config) { content = content || {}; config = config || {}; var meta = content.meta || {}; var worked = content.worked_example || {}; var workedSteps = Array.isArray(worked.steps) ? worked.steps : []; var drill = content.drill || {}; var variables = Array.isArray(drill.variables) ? drill.variables : []; var hints = Array.isArray(drill.hints) ? drill.hints : []; var totalRounds = Math.max(1, Math.floor(Number(drill.rounds) || 5)); var tolerance = Number(drill.tolerance); if (!isFinite(tolerance) || tolerance < 0) tolerance = 0.01; var unit = drill.unit != null ? String(drill.unit) : ""; var gm = content.game_mode && content.game_mode.enabled ? content.game_mode : null; var personalBest = config.personal_best === undefined ? null : config.personal_best; // ---- state ------------------------------------------------------------ var phase = "worked"; // worked -> drill -> done var workedRevealed = workedSteps.length ? 1 : 0; var roundIndex = 0; // 0-based; current round is roundIndex + 1 var currentRound = null; // {values, expected, answered, hintsShown} var correctCount = 0; var answeredCount = 0; var streak = 0; var bestStreak = 0; var points = 0; var completed = false; var bestReportedScore = -1; var secondsLeft = gm ? Math.max(1, Math.floor(Number(gm.timer_seconds) || 60)) : 0; var timerHandle = null; // ---- static frame ------------------------------------------------------- rootEl.textContent = ""; var styleTag = document.createElement("style"); styleTag.textContent = STYLE; rootEl.appendChild(styleTag); var header = el("div", "cp-header"); var titleWrap = el("div"); titleWrap.appendChild(el("h1", null, meta.title || "Calculation practice")); header.appendChild(titleWrap); var timerEl = null; if (gm) { timerEl = el("div", "us-timer"); timerEl.setAttribute("role", "timer"); timerEl.setAttribute("aria-label", "Time remaining"); header.appendChild(timerEl); } rootEl.appendChild(header); var bestBanner = null; if (gm && personalBest != null) { bestBanner = el("div", "cp-best-banner", "Beat your best: your best practice run so far scored " + personalBest + " points."); rootEl.appendChild(bestBanner); } var progress = el("div", "us-progress"); var progressFill = el("div"); progress.appendChild(progressFill); rootEl.appendChild(progress); var stage = el("div"); rootEl.appendChild(stage); function setProgress(fraction) { progressFill.style.width = Math.max(0, Math.min(100, Math.round(fraction * 100))) + "%"; } // ---- timer (game mode) -------------------------------------------------- function renderTimer() { if (!timerEl) return; var m = Math.floor(secondsLeft / 60); var s = secondsLeft % 60; timerEl.textContent = m + ":" + (s < 10 ? "0" : "") + s; if (secondsLeft < 10) timerEl.classList.add("low"); } function startTimer() { if (!gm || timerHandle) return; renderTimer(); timerHandle = setInterval(function () { // The clock never punishes listening: hold while the audio guide plays. if (window.SimSDK && SimSDK.narration && SimSDK.narration.active()) return; secondsLeft--; if (secondsLeft <= 0) { secondsLeft = 0; renderTimer(); clearInterval(timerHandle); timerHandle = null; finishDrill(true); } else { renderTimer(); } }, 1000); } function stopTimer() { if (timerHandle) { clearInterval(timerHandle); timerHandle = null; } } // ---- worked example ----------------------------------------------------- function renderWorked() { stage.textContent = ""; setProgress(0); var card = el("div", "us-card"); card.appendChild(el("h2", null, "Worked example")); card.appendChild(el("p", "cp-question", worked.prompt || "Follow the steps below to see how this calculation works.")); var list = el("div"); for (var i = 0; i < workedRevealed && i < workedSteps.length; i++) { var s = workedSteps[i] || {}; var row = el("div", "cp-step"); var head = el("div"); head.appendChild(el("span", "cp-step-num", String(i + 1))); head.appendChild(document.createTextNode(s.explanation || "")); row.appendChild(head); if (s.expression) { var code = el("code", "cp-expr", s.expression); row.appendChild(code); } list.appendChild(row); } card.appendChild(list); var actions = el("div", "us-footer-actions"); if (workedRevealed < workedSteps.length) { var moreBtn = el("button", "us-btn us-btn-primary", "Show the next step"); moreBtn.type = "button"; moreBtn.addEventListener("click", function () { workedRevealed++; SimSDK.interaction({ action: "worked_step", step_index: workedRevealed - 1 }); renderWorked(); var steps = stage.querySelectorAll(".cp-step"); var last = steps.length ? steps[steps.length - 1] : null; if (last && last.scrollIntoView) last.scrollIntoView({ block: "nearest" }); }); actions.appendChild(moreBtn); } else { var startBtn = el("button", "us-btn us-btn-primary", "Start practising"); startBtn.type = "button"; startBtn.addEventListener("click", function () { SimSDK.interaction({ action: "start_drill" }); startDrill(); }); actions.appendChild(startBtn); } card.appendChild(actions); stage.appendChild(card); } // ---- drill -------------------------------------------------------------- function makeRound() { // Roll variable values until the expected answer is a finite number. // Returns null (never throws) if no solvable combination can be found. try { var attempt, values, expected; for (attempt = 0; attempt < 60; attempt++) { values = {}; for (var i = 0; i < variables.length; i++) { var v = variables[i] || {}; if (v.name) values[v.name] = rollValue(v); } expected = evaluateExpression(drill.solution_expression, values); if (isFinite(expected)) return { values: values, expected: expected, answered: false, hintsShown: 0 }; } // Deterministic fallback: everything at its minimum. values = {}; for (var j = 0; j < variables.length; j++) { var vv = variables[j] || {}; if (vv.name) values[vv.name] = Number(vv.min) || 0; } expected = evaluateExpression(drill.solution_expression, values); if (isFinite(expected)) return { values: values, expected: expected, answered: false, hintsShown: 0 }; } catch (err) { /* fall through to null */ } return null; } function showSetupError() { stopTimer(); stage.textContent = ""; var errCard = el("div", "us-card"); errCard.appendChild(el("h2", null, "This activity couldn't be set up")); errCard.appendChild(el("p", "us-muted", "The calculation behind this practice couldn't be read. Please let your trainer know so it can be fixed.")); stage.appendChild(errCard); } function startDrill() { phase = "drill"; roundIndex = 0; currentRound = makeRound(); if (!currentRound) { showSetupError(); return; } renderRound(); if (gm) startTimer(); } function parseAnswer(text) { var t = String(text == null ? "" : text).trim().replace(/,/g, "."); if (!/^[+-]?(?:\d+\.?\d*|\.\d+)$/.test(t)) return null; var n = parseFloat(t); return isFinite(n) ? n : null; } function renderRound() { stage.textContent = ""; setProgress(roundIndex / totalRounds); var card = el("div", "us-card"); var metaRow = el("div", "cp-meta-row"); var label = el("div", "us-muted", "Question " + (roundIndex + 1) + " of " + totalRounds); metaRow.appendChild(label); if (gm && gm.streak_bonus && streak >= 2) { metaRow.appendChild(el("span", "cp-streak", "Streak: " + streak)); } card.appendChild(metaRow); card.appendChild(el("p", "cp-question", substituteTemplate(drill.template, currentRound.values))); var answerRow = el("div", "cp-answer-row"); var input = el("input", "us-input"); input.type = "text"; input.setAttribute("inputmode", "decimal"); input.setAttribute("autocomplete", "off"); input.setAttribute("aria-label", "Your answer" + (unit ? " in " + unit : "")); input.placeholder = "Your answer"; answerRow.appendChild(input); if (unit) answerRow.appendChild(el("span", "cp-unit", unit)); card.appendChild(answerRow); var feedbackHolder = el("div"); feedbackHolder.setAttribute("aria-live", "polite"); card.appendChild(feedbackHolder); var hintHolder = el("div"); card.appendChild(hintHolder); var hintList = el("ul", "cp-hint-list"); hintHolder.appendChild(hintList); renderHints(hintList); var actions = el("div", "us-footer-actions"); var checkBtn = el("button", "us-btn us-btn-primary", "Check my answer"); checkBtn.type = "button"; actions.appendChild(checkBtn); var hintBtn = null; if (hints.length) { hintBtn = el("button", "us-btn", currentRound.hintsShown === 0 ? "Show a hint" : "Show another hint"); hintBtn.type = "button"; if (currentRound.hintsShown >= hints.length) hintBtn.disabled = true; hintBtn.addEventListener("click", function () { if (currentRound.hintsShown >= hints.length) return; currentRound.hintsShown++; SimSDK.interaction({ action: "hint", round: roundIndex + 1, hint_index: currentRound.hintsShown - 1 }); renderHints(hintList); hintBtn.textContent = "Show another hint"; if (currentRound.hintsShown >= hints.length) hintBtn.disabled = true; }); actions.appendChild(hintBtn); } card.appendChild(actions); stage.appendChild(card); function submit() { if (currentRound.answered) return; var given = parseAnswer(input.value); if (given == null) { feedbackHolder.textContent = ""; feedbackHolder.appendChild(el("div", "us-feedback us-feedback-info", "Type a number to check your answer.")); input.focus(); return; } currentRound.answered = true; answeredCount++; var expected = currentRound.expected; var correct = Math.abs(given - expected) <= tolerance; if (SimSDK.fx) { if (correct) SimSDK.fx.correct(); else SimSDK.fx.wrong(); } if (correct) { correctCount++; streak++; if (streak > bestStreak) bestStreak = streak; if (gm) { points += 100; if (gm.streak_bonus && streak >= 2) points += (streak - 1) * 20; } } else { streak = 0; } SimSDK.step("round_" + (roundIndex + 1), { round: roundIndex + 1, correct: correct, expected: expected, given: given }); input.disabled = true; checkBtn.disabled = true; if (hintBtn) hintBtn.disabled = true; feedbackHolder.textContent = ""; var fb; if (correct) { fb = el("div", "us-feedback us-feedback-correct", "Nice work — " + fmtNumber(expected) + (unit ? " " + unit : "") + " is right." + (gm && gm.streak_bonus && streak >= 2 ? " Streak bonus earned!" : "")); } else { fb = el("div", "us-feedback us-feedback-incorrect", "Not quite. The answer here is " + fmtNumber(expected) + (unit ? " " + unit : "") + ". You gave " + fmtNumber(given) + (unit ? " " + unit : "") + " — have another look at the worked example approach and try the next one."); } feedbackHolder.appendChild(fb); var nextActions = el("div", "us-footer-actions"); var nextBtn = el("button", "us-btn us-btn-primary", roundIndex + 1 < totalRounds ? "Next question" : "See how you went"); nextBtn.type = "button"; nextBtn.addEventListener("click", function () { if (roundIndex + 1 < totalRounds) { roundIndex++; currentRound = makeRound(); if (!currentRound) { finishDrill(false); return; } renderRound(); } else { finishDrill(false); } }); nextActions.appendChild(nextBtn); card.appendChild(nextActions); nextBtn.focus(); } checkBtn.addEventListener("click", submit); input.addEventListener("keydown", function (e) { if (e.key === "Enter") { e.preventDefault(); submit(); } }); input.focus(); } function renderHints(listEl) { listEl.textContent = ""; for (var i = 0; i < currentRound.hintsShown && i < hints.length; i++) { listEl.appendChild(el("li", null, hints[i])); } } // ---- finish ------------------------------------------------------------- function finishDrill(timedOut) { if (phase === "done") return; phase = "done"; stopTimer(); setProgress(1); stage.textContent = ""; var score = correctCount / totalRounds; var card = el("div", "us-card"); var banner = el("div", "us-score-banner"); banner.appendChild(el("div", "big", correctCount + " / " + totalRounds)); banner.appendChild(el("div", "us-muted", gm ? "Practice score — " + points + " points this run" : "Practice score — questions answered correctly")); card.appendChild(banner); if (timedOut) { card.appendChild(el("div", "us-feedback us-feedback-info", "Time's up! You got through " + answeredCount + " of " + totalRounds + " questions and answered " + correctCount + " correctly. Another practice run will build your pace.")); } else if (correctCount === totalRounds) { card.appendChild(el("div", "us-feedback us-feedback-correct", "Nice work — you answered every question correctly. Each practice run uses fresh numbers, so try again any time to keep it sharp.")); } else { card.appendChild(el("div", "us-feedback us-feedback-info", "You answered " + correctCount + " of " + totalRounds + " correctly. The numbers change every run, so another practice is a fresh start.")); } if (gm && gm.streak_bonus && bestStreak >= 2) { card.appendChild(el("p", "us-muted", "Longest streak this run: " + bestStreak + " in a row.")); } var beaten = null; if (gm && personalBest != null) { beaten = points > personalBest; var bbText = beaten ? "You beat your best! " + points + " points, up from " + personalBest + "." : "Your best is still " + personalBest + " points — this run scored " + points + ". Another practice will get you there."; if (bestBanner) { bestBanner.textContent = bbText; if (beaten) bestBanner.classList.add("cp-beaten"); } else { card.appendChild(el("div", "cp-best-banner" + (beaten ? " cp-beaten" : ""), bbText)); } } // The numbers re-roll every run, so a fresh start is always worthwhile — // never leave the learner at a dead end after the score card. var actions = el("div", "us-footer-actions"); var againBtn = el("button", "us-btn us-btn-primary", "Practise again"); againBtn.type = "button"; againBtn.addEventListener("click", function () { SimSDK.interaction({ action: "practise_again" }); if (beaten) personalBest = points; correctCount = 0; answeredCount = 0; streak = 0; bestStreak = 0; points = 0; if (gm) { secondsLeft = Math.max(1, Math.floor(Number(gm.timer_seconds) || 60)); if (timerEl) timerEl.classList.remove("low"); } startDrill(); }); actions.appendChild(againBtn); card.appendChild(actions); stage.appendChild(card); // Report the first completion, and again only when a replay improves on // it — a weaker rerun must never downgrade an LMS grade already posted. var scoreNow = Math.round(score * 100) / 100; if (!completed || scoreNow > bestReportedScore) { completed = true; bestReportedScore = scoreNow; var result = { score: scoreNow, rounds_correct: correctCount, rounds_total: totalRounds }; if (gm) { result.points = points; result.personal_best = personalBest; if (beaten !== null) result.beat_personal_best = beaten; if (timedOut) result.timed_out = true; } SimSDK.complete(result); } } // ---- go ----------------------------------------------------------------- SimSDK.start({ title: meta.title || "Calculation practice" }); // Validate the solution expression up front so a bad expression renders a // calm message rather than breaking mid-drill. try { var probe = {}; for (var i = 0; i < variables.length; i++) { var v = variables[i] || {}; if (v.name) probe[v.name] = Number(v.min) || 1; } evaluateExpression(drill.solution_expression || "", probe); } catch (err) { showSetupError(); return; } renderWorked(); } window.UnitSimEngine = { mount: function (rootEl, contentJson, SimSDK, config) { try { mountInner(rootEl, contentJson || {}, SimSDK, config || {}); } catch (err) { try { rootEl.textContent = ""; var msg = document.createElement("p"); msg.className = "us-muted"; msg.textContent = "This practice activity couldn't load. Please refresh the page to try again."; rootEl.appendChild(msg); } catch (err2) { /* nothing left to do */ } } } }; })();