with identical metrics, scroll-synced. Built at runtime so +// the no-JS page keeps plain server-rendered textareas. +import { specEditor, codeEditor } from './tutorial-dom.mjs'; +import { highlightTokens } from './highlight.mjs'; +import { esc } from './report-colors.mjs'; + +const highlightRenderers = []; + +export function setupHighlight(editor) { + const wrap = document.createElement('div'); + wrap.className = 'editor-wrap'; + const pre = document.createElement('pre'); + pre.className = 'editor-highlight'; + pre.setAttribute('aria-hidden', 'true'); + const code = document.createElement('code'); + pre.appendChild(code); + editor.parentNode.insertBefore(wrap, editor); + wrap.appendChild(pre); + wrap.appendChild(editor); + editor.classList.add('editor-overlaid'); + const sync = () => { + pre.scrollTop = editor.scrollTop; + pre.scrollLeft = editor.scrollLeft; + }; + const render = () => { + // trailing newline keeps the pre's last line height in step with the textarea + code.innerHTML = highlightTokens(esc(editor.value)) + '\n'; + sync(); + }; + editor.addEventListener('input', render); + editor.addEventListener('scroll', sync); + highlightRenderers.push(render); + render(); +} + +// call after every programmatic .value assignment (seeding, resume, reset) +export function refreshHighlights() { + for (const render of highlightRenderers) render(); +} + +// Both editors carry a native vertical resize grip, and a drag writes an inline +// height onto that one textarea only. The grid stretches the panes to the +// taller side, but a shorter inline height overrides the CSS fill, so dragging +// each grip in turn would drift the two windows apart. Mirror whichever grip is +// dragged onto the other editor so the left and right windows stay one height. +export function syncEditorHeights() { + if (typeof ResizeObserver === 'undefined') return; + const editors = [specEditor, codeEditor]; + let shared = ''; // the height last propagated to both, as an inline string + const observer = new ResizeObserver(() => { + for (const editor of editors) { + const height = editor.style.height; // set by a resize drag, else '' + if (height && height !== shared) { + shared = height; + for (const other of editors) { + if (other !== editor) other.style.height = height; + } + return; // the mirrored write settles to `shared`, so no feedback loop + } + } + }); + for (const editor of editors) observer.observe(editor); +} diff --git a/src/scripts/tutorial-persistence.mjs b/src/scripts/tutorial-persistence.mjs new file mode 100644 index 0000000..fb4a26e --- /dev/null +++ b/src/scripts/tutorial-persistence.mjs @@ -0,0 +1,165 @@ +// Persistence for the /learn/ engine: in-flight buffers (BUFFERS_KEY), +// completions (PROGRESS_KEY) and per-step ring progress (STEPS_KEY), plus the +// rail marks and the completed-chapter overlay those feed. All three stores +// are keyed by stable chapter id, never by index. +import { ide, setText, BUFFERS_KEY, PROGRESS_KEY, STEPS_KEY } from './tutorial-dom.mjs'; +import { loadStore, saveStore, loadStepEntry, progressEntry } from './tutorial-store.mjs'; +import { ringSvg, completionStatement } from './tutorial-util.mjs'; +import { + current, + currentIndex, + data, + panes, + assists, + assistedSteps, + checkTimer, +} from './tutorial-state.mjs'; + +// Pristine entries are deleted on save, so under the multi-file shape a +// stored entry always means real work; only legacy string entries can still +// equal the seeds. +export function storedPristine(chapter, stored) { + if (stored.panes) return false; + return stored.spec === chapter.spec.body && stored.code === chapter.variant.body; +} + +export function saveBuffers() { + if (!current || !panes) return; + const store = loadStore(BUFFERS_KEY); + const only = (pane) => (panes[pane].files.length === 1 ? panes[pane].files[0] : null); + const spec = only('spec'); + const code = only('code'); + const pristine = + spec && code && + spec.name === current.spec.file && spec.body === current.spec.body && + code.name === current.variant.file && code.body === current.variant.body; + if (pristine) { + delete store.chapters[current.id]; + } else { + const snapshot = (pane) => ({ + files: panes[pane].files.map((f) => ({ name: f.name, body: f.body })), + active: panes[pane].active, + }); + store.chapters[current.id] = { + rev: current.rev, + lang: data.lang, + savedAt: new Date().toISOString(), + panes: { spec: snapshot('spec'), code: snapshot('code') }, + }; + } + saveStore(BUFFERS_KEY, store); +} + +export function deleteBufferEntry(id) { + const store = loadStore(BUFFERS_KEY); + delete store.chapters[id]; + saveStore(BUFFERS_KEY, store); +} + +// Written exactly once per chapter: when its done-condition first passes +// after a real (non-silent) Run in this browser. +export function completeChapter(chapter) { + const store = loadStore(PROGRESS_KEY); + if (store.chapters[chapter.id]) return; + const entry = { + title: chapter.title, + rev: chapter.rev, + lang: data.lang, + completedAt: new Date().toISOString(), + assists: { help: assists.help, auto: assists.auto }, + }; + store.chapters[chapter.id] = entry; + saveStore(PROGRESS_KEY, store); + saveBuffers(); // keep the solved files - revisits restore them under the overlay + clearTimeout(checkTimer); + renderRailMarks(); + setCompletedOverlay(entry); +} + +export function deleteProgressEntry(id) { + const store = loadStore(PROGRESS_KEY); + delete store.chapters[id]; + saveStore(PROGRESS_KEY, store); +} + +export function saveStepProgress(id, done) { + const store = loadStore(STEPS_KEY); + const prev = loadStepEntry(store, id); + // only leading solved steps keep an assist mark; a regressed step starts over + const assisted = [...assistedSteps].filter((n) => n < done).sort((a, b) => a - b); + const unchanged = + prev.done === done && + prev.assisted.length === assisted.length && + prev.assisted.every((n, i) => n === assisted[i]); + if (unchanged) return; + if (done === 0) delete store.chapters[id]; + else store.chapters[id] = { done, assisted }; + saveStore(STEPS_KEY, store); + renderRailMarks(); +} + +export function deleteStepsEntry(id) { + const store = loadStore(STEPS_KEY); + delete store.chapters[id]; + saveStore(STEPS_KEY, store); +} + +// Each chapter link carries a small SVG donut split into one arc per step, +// running clockwise from 12 o'clock: steps solved so far draw bold, the rest +// stay thin and muted. A step the user cleared themselves draws green; one +// finished with an assist draws amber. Once a chapter is completed its ring +// gives way to the ✓ check, so exactly one symbol shows per chapter. +export function renderRailMarks() { + const progress = loadStore(PROGRESS_KEY); + const steps = loadStore(STEPS_KEY); + document.querySelectorAll('.ch-ring[data-ring]').forEach((ring) => { + const id = ring.getAttribute('data-ring'); + const total = Math.trunc(Number(ring.getAttribute('data-steps'))) || 0; + if (total < 1) return; + // a completed chapter hands its slot to the check; only in-progress + // chapters draw a ring. stale counts clamp to the ring's step total. + ring.hidden = Boolean(progress.chapters[id]); + if (ring.hidden) return; + const entry = loadStepEntry(steps, id); + const done = Math.min(total, entry.done); + const assisted = new Set(entry.assisted.filter((n) => n < done)); + ring.innerHTML = ringSvg(total, done, assisted); + }); + const legend = document.querySelector('.legend-steps'); + if (legend) { + legend.hidden = false; + const demo = legend.querySelector('[data-ring-demo]'); + if (demo) demo.innerHTML = ringSvg(3, 1); + } + let any = false; + document.querySelectorAll('.ch-mark[data-mark]').forEach((mark) => { + const entry = progress.chapters[mark.getAttribute('data-mark')]; + const assisted = entry && entry.assists && entry.assists.help + entry.assists.auto > 0; + mark.classList.toggle('is-done', Boolean(entry) && !assisted); + mark.classList.toggle('is-assisted', Boolean(assisted)); + if (entry) { + any = true; + mark.closest('a').title = assisted ? 'completed with assists' : 'completed'; + } + }); + const reset = document.getElementById('reset-progress'); + if (reset) reset.hidden = !any; +} + +// A finished chapter shows its solved files blurred behind a check card saying +// when and how it was completed; everything else inside the IDE goes inert +// until "Reset chapter". Pass null to hide the overlay again. +export function setCompletedOverlay(entry) { + const overlay = document.getElementById('done-overlay'); + if (!overlay) return; + overlay.hidden = !entry; + for (const child of ide.children) { + if (child !== overlay) child.inert = Boolean(entry); + } + if (entry) setText('done-text', completionStatement(entry)); +} + +export function chapterCompleteText() { + const next = data.chapters[currentIndex + 1]; + return 'Chapter complete ✓' + (next ? ' - up next: ' + (currentIndex + 2) + ' · ' + next.title : ' - that was the last one!'); +} diff --git a/src/scripts/tutorial-runner.mjs b/src/scripts/tutorial-runner.mjs new file mode 100644 index 0000000..a7721c0 --- /dev/null +++ b/src/scripts/tutorial-runner.mjs @@ -0,0 +1,115 @@ +// The runner: each Run spawns a fresh module worker that executes the real +// flashtrace release build against the editor buffers; chapter checks then +// evaluate the worker's structured result. Silent background runs keep the +// step state live as the user types; a real Run additionally prints output, +// records `run: true` steps and can complete the chapter. +import { argvInput, terminal, runButton, RUN_TIMEOUT_MS } from './tutorial-dom.mjs'; +import { colorizeReport, esc } from './report-colors.mjs'; +import { safeCheck } from './tutorial-util.mjs'; +import { recordRealRun, updateStepUi } from './tutorial-steps.mjs'; +import { completeChapter } from './tutorial-persistence.mjs'; +import { + typing, + active, + current, + panes, + checkTimer, + lastResult, + setActive, + setLastResult, + setCheckTimer, +} from './tutorial-state.mjs'; + +export function currentArgv() { + const raw = argvInput ? argvInput.value : ''; + return raw.trim().split(/\s+/).filter(Boolean); +} + +function showTerminal(html) { + terminal.innerHTML = html; +} + +function finishRun() { + if (!active) return; + clearTimeout(active.watchdog); + active.worker.terminate(); + setActive(null); + runButton.disabled = false; +} + +export function scheduleSilentRun() { + if (current && current.free) return; // nothing evaluates sandbox runs in the background + clearTimeout(checkTimer); + setCheckTimer(setTimeout(() => run(true), 800)); +} + +export function run(silent) { + if (typing) return; // never run against a half-typed patch + if (active) { + if (silent) return; // a real Run preempts a background check, not vice versa + if (active.silent) finishRun(); + else return; + } + if (typeof Worker === 'undefined') { + if (!silent) showTerminal('This browser cannot run workers - the live terminal is unavailable.'); + return; + } + + const argv = currentArgv(); + const files = {}; + for (const pane of ['spec', 'code']) { + for (const file of panes[pane].files) files[file.name] = file.body; + } + const prompt = '$ ' + esc(['npx flashtrace'].concat(argv).join(' ')) + '\n'; + + if (!silent) { + runButton.disabled = true; + showTerminal(prompt + 'running…'); + } + + const worker = new Worker(new URL('./tutorial-worker.js', import.meta.url), { type: 'module' }); + const watchdog = setTimeout(() => { + const wasSilent = active && active.silent; + finishRun(); + if (!wasSilent) showTerminal(prompt + 'the run did not finish within 5 seconds and was stopped'); + }, RUN_TIMEOUT_MS); + setActive({ worker, watchdog, silent }); + + worker.onmessage = (event) => { + const wasSilent = active && active.silent; + finishRun(); + const result = event.data; + if (!result.ok) { + if (!wasSilent) showTerminal(prompt + 'failed to load the flashtrace bundle: ' + esc(result.error) + ''); + return; + } + if (!wasSilent) { + const body = result.output ? colorizeReport(result.output) + '\n' : ''; + showTerminal(prompt + body + 'exit ' + result.exitCode + ''); + } + // checks read r.spec / r.code as raw text: with several files per pane + // they see the pane's files joined, so work spread over added files still + // satisfies text-based checks; r.files carries the run's input snapshot + const paneText = (pane) => panes[pane].files.map((f) => f.body).join('\n'); + setLastResult(Object.assign({}, result.analysis, { + exitCode: result.exitCode, + argv, + files, + spec: paneText('spec'), + code: paneText('code'), + })); + if (!wasSilent) recordRealRun(); + if (current && !current.free && result.analysis && !wasSilent && safeCheck(current.done, lastResult)) { + completeChapter(current); + } + updateStepUi(!wasSilent); + document.dispatchEvent(new CustomEvent('flashtrace:run', { detail: { result, silent: wasSilent } })); + }; + worker.onerror = (event) => { + const wasSilent = active && active.silent; + finishRun(); + if (!wasSilent) showTerminal(prompt + 'worker error: ' + esc(event.message || 'unknown') + ''); + }; + + worker.postMessage({ files, argv }); +} diff --git a/src/scripts/tutorial-state.mjs b/src/scripts/tutorial-state.mjs new file mode 100644 index 0000000..577100e --- /dev/null +++ b/src/scripts/tutorial-state.mjs @@ -0,0 +1,43 @@ +// Shared engine state for the /learn/ modules. Everything imports these as +// live bindings, so reads always see the current value; reassignment happens +// only through the setters below (ES module bindings are read-only to +// importers). Object/Set members are mutated in place by their owners. + +export let data = null; // compiled chapter data, or null in the bare runner +export let current = null; // active chapter object +export let currentIndex = 0; +// Editable files, one list per pane: the left pane holds the Markdown spec +// side, the right the code side. Each pane shows its active file in the +// textarea; the editors' input listeners keep the active body in sync, so the +// model is always current. Chapters marked `locked` render padlocks instead +// of close buttons and a disabled "+". +export let panes = null; // { spec: { files: [{ name, body }], active }, code: { ... } } +export let assists = { help: 0, auto: 0 }; // in-memory per chapter visit +export let assistedSteps = new Set(); // step indices solved with an assist, current chapter +// `run: true` steps ask the user to press Run: an index lands here once a +// real, user-triggered run happened while every step before it passed, so +// background silent runs never clear one. Seeded from the persisted done +// count on open, so a revisit does not regress past a run already made. +export let realRunCleared = new Set(); +export let lastResult = null; // r-context of the latest (also silent) run +export let active = null; // { worker, watchdog, silent } of the run in flight +export let saveTimer = null; +export let checkTimer = null; +export let lastSyncedStep = null; // step the accordion was last folded to; guards manual folds +export let typing = false; // typewriter in flight - runs and assists wait +export let assistRestoreFocus = null; + +export function setData(v) { data = v; } +export function setCurrent(v) { current = v; } +export function setCurrentIndex(v) { currentIndex = v; } +export function setPanes(v) { panes = v; } +export function setAssists(v) { assists = v; } +export function setAssistedSteps(v) { assistedSteps = v; } +export function setRealRunCleared(v) { realRunCleared = v; } +export function setLastResult(v) { lastResult = v; } +export function setActive(v) { active = v; } +export function setSaveTimer(v) { saveTimer = v; } +export function setCheckTimer(v) { checkTimer = v; } +export function setLastSyncedStep(v) { lastSyncedStep = v; } +export function setTyping(v) { typing = v; } +export function setAssistRestoreFocus(v) { assistRestoreFocus = v; } diff --git a/src/scripts/tutorial-steps.mjs b/src/scripts/tutorial-steps.mjs new file mode 100644 index 0000000..36914b0 --- /dev/null +++ b/src/scripts/tutorial-steps.mjs @@ -0,0 +1,118 @@ +// The step guidance panel between the intro and the IDE: one per +// step, rebuilt on every chapter switch and re-synced after every analysis +// (same structure as the server-rendered chapter 1 in tutorial.mjs). Steps +// behind the current one grey out behind a check, the current one unfolds; at +// most one step is ever unfolded (a proper accordion). +import { setText } from './tutorial-dom.mjs'; +import { esc } from './report-colors.mjs'; +import { safeCheck } from './tutorial-util.mjs'; +import { progressEntry } from './tutorial-store.mjs'; +import { saveStepProgress, chapterCompleteText } from './tutorial-persistence.mjs'; +import { + current, + lastResult, + assistedSteps, + realRunCleared, + lastSyncedStep, + setLastSyncedStep, +} from './tutorial-state.mjs'; + +// Modern browsers make same-`name` details mutually exclusive natively; this +// mirrors that where the attribute is unsupported. toggle does not bubble, +// so it is captured at the list. +export function initStepAccordion() { + const list = document.getElementById('step-items'); + if (!list || 'name' in document.createElement('details')) return; + list.addEventListener( + 'toggle', + (event) => { + if (!event.target.open) return; + for (const other of list.querySelectorAll('details[open]')) { + if (other !== event.target) other.open = false; + } + }, + true, + ); +} + +export function renderStepList(chapter) { + const section = document.getElementById('step-list'); + const list = document.getElementById('step-items'); + if (!section || !list) return; + section.hidden = Boolean(chapter.free); + if (section.hidden) return; + list.innerHTML = chapter.steps + .map( + (step, i) => + '' + + (i + 1) + ' · ' + esc(step.title) + + '' + esc(step.explain) + '', + ) + .join(''); + syncStepList(0, true); +} + +// classes always mirror progress; the fold only snaps to the current step when +// that step actually changes (chapter switch, real progress) or on an explicit +// reset (force) - so background silent runs never yank a step the user opened +// to explore back to the current one. +export function syncStepList(currentIndex, force) { + const list = document.getElementById('step-items'); + if (!list) return; + const refold = force || currentIndex !== lastSyncedStep; + Array.from(list.children).forEach((item, i) => { + item.classList.toggle('is-done', i < currentIndex); + item.classList.toggle('is-assisted', i < currentIndex && assistedSteps.has(i)); + item.classList.toggle('is-current', i === currentIndex); + const details = item.querySelector('details'); + if (details && refold) details.open = i === currentIndex; + }); + setLastSyncedStep(currentIndex); +} + +// current step = index of the first failing check; users may type ahead, +// paste solutions or re-break earlier steps - this always re-converges. +// A `run: true` step additionally needs its real run on record. +export function firstFailingIndex() { + if (!current || !lastResult || !lastResult.items) return null; + for (let i = 0; i < current.steps.length; i++) { + const step = current.steps[i]; + if (!safeCheck(step.check, lastResult) || (step.run && !realRunCleared.has(i))) return i; + } + return current.steps.length; +} + +// After a real Run: walk the steps in order and put every `run: true` step +// reached with all its predecessors passing on record - this run was it. +export function recordRealRun() { + if (!current || current.free || !lastResult || !lastResult.items) return; + for (let i = 0; i < current.steps.length; i++) { + const step = current.steps[i]; + if (step.run) realRunCleared.add(i); + if (!safeCheck(step.check, lastResult) || (step.run && !realRunCleared.has(i))) return; + } +} + +export function updateStepUi(fromRealRun) { + if (!current || current.free || !lastResult || !lastResult.items) return; + const steps = current.steps; + const firstFailing = firstFailingIndex(); + const solved = safeCheck(current.done, lastResult); + saveStepProgress(current.id, firstFailing); + const helpBtn = document.getElementById('help-btn'); + if (helpBtn) helpBtn.disabled = false; + const completed = Boolean(progressEntry(current.id)); + if (solved && (completed || fromRealRun)) { + setText('step-progress', chapterCompleteText()); + } else if (firstFailing >= steps.length) { + setText('step-progress', solved ? 'All steps done - Run to finish the chapter.' : 'All steps done.'); + } else { + setText('step-progress', 'Step ' + (firstFailing + 1) + ' of ' + steps.length); + } + syncStepList(firstFailing); + document.dispatchEvent( + new CustomEvent('flashtrace:steps', { + detail: { chapter: current.id, firstFailing, solved, fromRealRun }, + }), + ); +} diff --git a/src/scripts/tutorial-store.mjs b/src/scripts/tutorial-store.mjs new file mode 100644 index 0000000..9720a5d --- /dev/null +++ b/src/scripts/tutorial-store.mjs @@ -0,0 +1,97 @@ +// localStorage-backed stores (ft-tutorial-*) and the server-embedded chapter +// data. Every store degrades to "empty" on unparseable or foreign-versioned +// data so a bad entry never crashes the page. +import { PROGRESS_KEY, BUFFERS_KEY, STEPS_KEY } from './tutorial-dom.mjs'; + +export function loadStore(key) { + // unparseable or foreign-versioned data degrades to "empty" without crashing + try { + const parsed = JSON.parse(localStorage.getItem(key)); + if (parsed && parsed.v === 1 && parsed.chapters && typeof parsed.chapters === 'object') { + return parsed; + } + } catch { + /* fall through */ + } + return { v: 1, chapters: {} }; +} + +export function saveStore(key, store) { + try { + localStorage.setItem(key, JSON.stringify(store)); + } catch { + /* private mode etc. - persistence is best-effort */ + } +} + +export function removeStores() { + try { + localStorage.removeItem(PROGRESS_KEY); + localStorage.removeItem(BUFFERS_KEY); + localStorage.removeItem(STEPS_KEY); + } catch { + /* ignore */ + } +} + +export function progressEntry(id) { + return loadStore(PROGRESS_KEY).chapters[id]; +} + +// normalize a STEPS_KEY entry to { done, assisted }; legacy entries stored a +// bare solved-step count, which maps onto an all-self (no-assist) chapter +export function loadStepEntry(store, id) { + const raw = store.chapters[id]; + if (typeof raw === 'number') return { done: Math.max(0, Math.trunc(raw) || 0), assisted: [] }; + if (raw && typeof raw === 'object') { + const done = Math.max(0, Math.trunc(Number(raw.done)) || 0); + const assisted = Array.isArray(raw.assisted) + ? [...new Set(raw.assisted.map((n) => Math.trunc(Number(n))).filter((n) => Number.isFinite(n) && n >= 0))] + : []; + return { done, assisted }; + } + return { done: 0, assisted: [] }; +} + +export function loadChapterData() { + try { + const el = document.getElementById('tutorial-data'); + const data = JSON.parse(el.textContent); + if (data.v !== 1 || !Array.isArray(data.chapters) || data.chapters.length === 0) return null; + // checks/done/solve ship as source text of pure, closure-free arrows + const compile = (src) => new Function('return (' + src + ')')(); + for (const chapter of data.chapters) { + chapter.done = compile(chapter.done); + for (const step of chapter.steps) { + step.check = compile(step.check); + if (step.solve) step.solve = compile(step.solve); + } + chapter.variants = { [data.lang]: chapter.variant }; // applyStep's shape + } + return data; + } catch (err) { + console.warn('tutorial: chapter data unavailable, running as a plain editor -', err); + return null; + } +} + +// The free editor: a chapter-shaped sandbox living outside data.chapters. It +// has no steps, goal or completion - just two empty files and the real CLI. +// Its buffers persist under the same store as any chapter, keyed 'editor'. +export const FREE_EDITOR = { + id: 'editor', + free: true, + rev: 0, + title: 'Free editor', + intro: + 'A blank project, all yours: write any spec and code and trace them with the real flashtrace release. No goals, no checks - the chapters in the rail are there whenever you want guidance.', + docs: [ + { label: 'Usage Guide', href: '/docs/usage/' }, + { label: 'Overview', href: '/docs/' }, + ], + argv: [], + spec: { file: 'spec.md', body: '' }, + variant: { file: 'script.js', body: '' }, + steps: [], + done: () => false, +}; diff --git a/src/scripts/tutorial-util.mjs b/src/scripts/tutorial-util.mjs new file mode 100644 index 0000000..c79896b --- /dev/null +++ b/src/scripts/tutorial-util.mjs @@ -0,0 +1,71 @@ +// Pure helpers shared across the /learn/ modules: no DOM, no shared state. + +export function relativeTime(iso) { + const then = Date.parse(iso); + if (Number.isNaN(then)) return 'earlier'; + const minutes = Math.round((Date.now() - then) / 60000); + if (minutes < 2) return 'moments ago'; + if (minutes < 90) return minutes + ' minutes ago'; + const hours = Math.round(minutes / 60); + if (hours < 36) return hours + ' hours ago'; + return Math.round(hours / 24) + ' days ago'; +} + +export function safeCheck(fn, r) { + try { + return fn(r) === true; + } catch { + return false; + } +} + +// shortest edit between the buffer and the patched buffer - typed as one span +export function diffRange(oldText, newText) { + let prefix = 0; + while (prefix < oldText.length && prefix < newText.length && oldText[prefix] === newText[prefix]) prefix++; + let oldEnd = oldText.length; + let newEnd = newText.length; + while (oldEnd > prefix && newEnd > prefix && oldText[oldEnd - 1] === newText[newEnd - 1]) { + oldEnd--; + newEnd--; + } + return { start: prefix, oldEnd, insert: newText.slice(prefix, newEnd) }; +} + +// --- rail progress rings ----------------------------------------------------- + +function ringPoint(radius, deg) { + const rad = (deg * Math.PI) / 180; + return (8 + radius * Math.sin(rad)).toFixed(2) + ' ' + (8 - radius * Math.cos(rad)).toFixed(2); +} + +export function ringSvg(total, done, assisted) { + const radius = 6.25; + const cls = (i) => + 'seg' + (i < done ? (assisted && assisted.has(i) ? ' is-done is-assisted' : ' is-done') : ''); + let body; + if (total === 1) { + body = ''; + } else { + const span = 360 / total; + const gap = Math.min(18, span / 4); + body = Array.from({ length: total }, (_, i) => { + const from = i * span + gap / 2; + const to = (i + 1) * span - gap / 2; + const arc = 'A' + radius + ' ' + radius + ' 0 ' + (to - from > 180 ? 1 : 0) + ' 1 '; + return ''; + }).join(''); + } + return '' + body + ''; +} + +export function completionStatement(entry) { + const help = entry.assists ? entry.assists.help : 0; + const auto = entry.assists ? entry.assists.auto : 0; + const how = []; + if (help) how.push(help + (help === 1 ? ' hint' : ' hints')); + if (auto) how.push(auto + (auto === 1 ? ' auto-solved step' : ' auto-solved steps')); + return ( + 'Completed ' + relativeTime(entry.completedAt) + (how.length ? ' with ' + how.join(' and ') : ' without assists') + '.' + ); +} diff --git a/src/scripts/tutorial-worker.js b/src/scripts/tutorial-worker.js new file mode 100644 index 0000000..5d76a68 --- /dev/null +++ b/src/scripts/tutorial-worker.js @@ -0,0 +1,82 @@ +// Module worker for /learn/: executes the real, release-pinned flashtrace +// bundle (node:* imports rewritten to ./shims/ at build time) against the +// editor buffers as in-memory files, then derives structured results from the +// bundle's exported library surface for the chapter checks. +// +// Protocol: one { files: { name: text }, argv: [extra args] } message in, one +// result message out. The page spawns a fresh worker per run (fresh module +// graph, no state leaks) and terminates it afterwards. + +import { analyzeBuffers } from './chapter-utils.mjs'; +import processShim from './shims/process.mjs'; + +// The bundle references the `process` global directly in one place (esbuild +// keeps globals as-is); Node provides it, a worker does not - seed it with +// the same shim the rewritten `node:process` imports resolve to. +globalThis.process = processShim; + +const BUNDLE_URL = new URL('./flashtrace.mjs', import.meta.url); + +const output = []; +let exitCode = null; +let exitSeen; +const exited = new Promise((resolve) => { + exitSeen = resolve; +}); + +const isExitSignal = (value) => + globalThis.__FtExitSignal !== undefined && value instanceof globalThis.__FtExitSignal; + +// The CLI ends every path in process.exit(): the shim throws an ExitSignal, +// runCli()'s catch handler logs it via console.error and rethrows a second +// one (code 2) as an unhandled rejection. Both are filtered from the output; +// the first signal observed carries the run's real exit code. +function recordExit(signal) { + if (exitCode === null) exitCode = signal.code; + exitSeen(); +} + +function capture(args) { + const signal = args.find(isExitSignal); + if (signal) { + recordExit(signal); + return; + } + output.push(args.map(String).join(' ')); +} + +console.log = (...args) => capture(args); +console.error = (...args) => capture(args); + +self.addEventListener('unhandledrejection', (event) => { + if (isExitSignal(event.reason)) { + event.preventDefault(); + recordExit(event.reason); + } +}); + +self.onmessage = async (event) => { + const { files, argv = [] } = event.data; + + const vfs = new Map(); + for (const [name, text] of Object.entries(files)) vfs.set('/project/' + name, text); + globalThis.__ftVfs = vfs; + globalThis.__ftArgv = ['node', decodeURIComponent(BUNDLE_URL.pathname), '/project', ...argv]; + + let mod; + try { + mod = await import(BUNDLE_URL.href); + } catch (err) { + postMessage({ ok: false, error: String(err) }); + return; + } + await exited; // resolved by the first ExitSignal - runCli() always exits + + let analysis = null; + try { + analysis = analyzeBuffers(mod, files, argv); + } catch { + // structured results are best-effort; the terminal output stands alone + } + postMessage({ ok: true, output: output.join('\n'), exitCode, analysis }); +}; diff --git a/src/scripts/tutorial.js b/src/scripts/tutorial.js new file mode 100644 index 0000000..0e2355e --- /dev/null +++ b/src/scripts/tutorial.js @@ -0,0 +1,176 @@ +// /learn/ page entry: wires the server-rendered IDE to the chapter engine and +// runner split across ./tutorial-*.mjs. Each Run spawns a fresh module worker +// that executes the real flashtrace release build against the editor buffers; +// chapter checks evaluate the worker's structured results. Progress and +// in-flight buffers persist in localStorage (ft-tutorial-*), keyed by stable +// chapter ids - never by index. Loaded as a module; browsers without module +// support keep the server-rendered read-only fallback. +import { + ide, + specEditor, + codeEditor, + terminal, + runButton, + argvInput, + setText, + PROGRESS_KEY, +} from './tutorial-dom.mjs'; +import { loadStore, removeStores, progressEntry, loadChapterData, FREE_EDITOR } from './tutorial-store.mjs'; +import { data, current, saveTimer, setData, setPanes, setSaveTimer, setRealRunCleared } from './tutorial-state.mjs'; +import { setupHighlight, syncEditorHeights } from './tutorial-highlight.mjs'; +import { activeFile, initTabs, renderAllTabs, seedBuffers } from './tutorial-files.mjs'; +import { + saveBuffers, + deleteBufferEntry, + deleteProgressEntry, + deleteStepsEntry, + setCompletedOverlay, + renderRailMarks, +} from './tutorial-persistence.mjs'; +import { initStepAccordion, syncStepList } from './tutorial-steps.mjs'; +import { run, scheduleSilentRun } from './tutorial-runner.mjs'; +import { initAssists } from './tutorial-assists.mjs'; +import { chapterById, openChapter } from './tutorial-chapters.mjs'; + +function init() { + // seed the pane model from the server-rendered buffers; openChapter replaces + // it, and the bare runner (no chapter data) keeps working on exactly this + setPanes({ + spec: { files: [{ name: ide.dataset.specFile || 'spec.md', body: specEditor.value }], active: 0 }, + code: { files: [{ name: ide.dataset.codeFile || 'code.js', body: codeEditor.value }], active: 0 }, + }); + setupHighlight(specEditor); + setupHighlight(codeEditor); + syncEditorHeights(); + specEditor.addEventListener('input', () => { + activeFile('spec').body = specEditor.value; + }); + codeEditor.addEventListener('input', () => { + activeFile('code').body = codeEditor.value; + }); + initTabs(); + renderAllTabs(); + runButton.addEventListener('click', () => run(false)); + for (const editor of [specEditor, codeEditor]) { + editor.addEventListener('keydown', (event) => { + if (event.key === 'Enter' && (event.ctrlKey || event.metaKey)) { + event.preventDefault(); + run(false); + } + }); + } + if (argvInput) { + argvInput.addEventListener('keydown', (event) => { + if (event.key === 'Enter') { + event.preventDefault(); + run(false); + } + }); + } + + initStepAccordion(); + setData(loadChapterData()); + if (!data) return; // bare runner: Run still works on the visible buffers + + for (const editor of [specEditor, codeEditor]) { + editor.addEventListener('input', () => { + clearTimeout(saveTimer); + setSaveTimer(setTimeout(saveBuffers, 400)); + scheduleSilentRun(); + }); + } + if (argvInput) argvInput.addEventListener('input', scheduleSilentRun); + + document.querySelectorAll('[data-chapter]').forEach((link) => { + link.addEventListener('click', (event) => { + event.preventDefault(); + openChapter(link.getAttribute('data-chapter')); + }); + }); + + const resetProgress = document.getElementById('reset-progress'); + if (resetProgress) { + resetProgress.addEventListener('click', () => { + if (window.confirm('Reset all tutorial progress and saved buffers?')) { + removeStores(); + window.location.reload(); + } + }); + } + const resetFiles = document.getElementById('reset-files'); + if (resetFiles) { + resetFiles.addEventListener('click', () => { + if (!current) return; + seedBuffers(); + deleteBufferEntry(current.id); + scheduleSilentRun(); + }); + } + + const doneView = document.getElementById('done-view'); + if (doneView) { + // peek at the solved files without forgetting the completion: hide the + // card and un-inert the IDE for this visit only. nothing is persisted, so + // reopening the chapter shows the card again. + doneView.addEventListener('click', () => setCompletedOverlay(null)); + } + + const doneReset = document.getElementById('done-reset'); + if (doneReset) { + doneReset.addEventListener('click', () => { + if (!current || current.free) return; + if (!window.confirm("Reset this chapter? Its completion and solved files are forgotten and the start files restored.")) return; + deleteProgressEntry(current.id); + deleteBufferEntry(current.id); + deleteStepsEntry(current.id); + setRealRunCleared(new Set()); + setCompletedOverlay(null); + seedBuffers(); + setText('step-progress', 'Run to check your progress.'); + syncStepList(0, true); + renderRailMarks(); + scheduleSilentRun(); + }); + } + + window.addEventListener('hashchange', () => { + const id = window.location.hash.slice(1); + if (current && id && id !== current.id) openChapter(id); + }); + + renderRailMarks(); + const fromHash = window.location.hash.slice(1); + const initial = + chapterById(fromHash) ?? + data.chapters.find((c) => !progressEntry(c.id)) ?? + data.chapters[0]; + openChapter(initial.id); + + // "Try it out" lands on #editor; on a first visit (no chapter ever + // completed) offer the guided route instead of two empty files + if (initial === FREE_EDITOR && Object.keys(loadStore(PROGRESS_KEY).chapters).length === 0) { + offerWelcome(); + } +} + +function offerWelcome() { + const modal = document.getElementById('welcome-modal'); + const learn = document.getElementById('welcome-learn'); + const editor = document.getElementById('welcome-editor'); + if (!modal || !learn || !editor || typeof modal.showModal !== 'function') return; + const close = (starter) => () => { + modal.close(); + learn.onclick = null; + editor.onclick = null; + starter(); + }; + learn.onclick = close(() => openChapter(data.chapters[0].id)); + editor.onclick = close(() => {}); + modal.oncancel = () => close(() => {})(); // Esc keeps the free editor + modal.showModal(); +} + +if (ide && specEditor && codeEditor && terminal && runButton) { + init(); + initAssists(); +} diff --git a/src/styles/site.css b/src/styles/site.css index ddadce0..edb0716 100644 --- a/src/styles/site.css +++ b/src/styles/site.css @@ -21,6 +21,8 @@ --ok: #15803d; --no: #b91c1c; --info: #0e7490; + --scroll-thumb: #d6d3d1; + --scroll-thumb-hover: #a8a29e; --shadow: 0 1px 3px rgb(0 0 0 / 0.08), 0 8px 24px rgb(0 0 0 / 0.06); --topbar-h: 3.5rem; color-scheme: light; @@ -45,6 +47,8 @@ --ok: #3fb950; --no: #f85149; --info: #56b6c2; + --scroll-thumb: #423c37; + --scroll-thumb-hover: #5a534d; --shadow: 0 1px 3px rgb(0 0 0 / 0.5), 0 8px 24px rgb(0 0 0 / 0.35); color-scheme: dark; } @@ -70,6 +74,8 @@ --ok: #3fb950; --no: #f85149; --info: #56b6c2; + --scroll-thumb: #423c37; + --scroll-thumb-hover: #5a534d; color-scheme: dark; } } @@ -173,6 +179,56 @@ button { } } +/* ---------- scrollbars ---------- */ + +/* WebKit/Blink: trackless rounded thumbs; the transparent border + + padding-box clip keeps a gutter so the thumb floats off the edge */ +::-webkit-scrollbar { + width: 12px; + height: 12px; +} + +::-webkit-scrollbar-track, +::-webkit-scrollbar-corner { + background: transparent; +} + +::-webkit-scrollbar-thumb { + background: var(--scroll-thumb); + border: 3px solid transparent; + border-radius: 999px; + background-clip: padding-box; +} + +::-webkit-scrollbar-thumb:hover { + background-color: var(--scroll-thumb-hover); +} + +/* slimmer bar for inner scroll areas (chapter/docs rails, toc) */ +.sidebar::-webkit-scrollbar, +.toc::-webkit-scrollbar { + width: 8px; +} + +.sidebar::-webkit-scrollbar-thumb, +.toc::-webkit-scrollbar-thumb { + border-width: 2px; +} + +/* Firefox has no ::-webkit-scrollbar - use the standard properties there. + Blink is excluded on purpose: setting scrollbar-color would replace the + nicer pseudo-element styling above with its plain square thumbs. */ +@supports not selector(::-webkit-scrollbar) { + * { + scrollbar-color: var(--scroll-thumb) transparent; + } + + .sidebar, + .toc { + scrollbar-width: thin; + } +} + /* ---------- top bar ---------- */ .topbar { @@ -358,9 +414,11 @@ button { display: inline-flex; align-items: center; padding: 0.6rem 1.25rem; + border: 0; border-radius: 8px; font-weight: 600; font-size: 0.95rem; + cursor: pointer; } .btn:hover { @@ -415,6 +473,8 @@ button { --tk-id: #f9c21d; --tk-kw: #e8964a; --tk-arrow: #56b6c2; + --scroll-thumb: #3f3c3a; + --scroll-thumb-hover: #57534e; border-radius: 10px; overflow: hidden; border: 1px solid #33302c; @@ -469,12 +529,37 @@ button { .ide-pane { min-width: 0; + /* column so the editor fills the pane; the grid stretches both panes to the + taller one, so whichever side is resized taller drives both to one height */ + display: flex; + flex-direction: column; +} + +/* the editor (no-JS) or its highlight wrap (JS overlay) grows to fill the pane, + keeping the left and right windows the same height */ +.ide-pane > .editor, +.ide-pane > .editor-wrap { + flex: 1 1 auto; +} + +.ide-pane > .editor-wrap > .editor { + height: 100%; } .ide-pane + .ide-pane { border-left: 1px solid #33302c; } +/* a noCode chapter has no source: the code pane disappears entirely and the + spec spreads across the full width */ +.ide-mock.no-code .ide-panes { + grid-template-columns: 1fr; +} + +.ide-mock.no-code .ide-pane + .ide-pane { + display: none; +} + .pane-tab { display: inline-block; padding: 0.35rem 1rem; @@ -795,7 +880,9 @@ button { align-self: start; max-height: calc(100vh - var(--topbar-h)); overflow-y: auto; - padding: 1.5rem 0.5rem 2rem 0; + /* the scroll container clips horizontally - keep left padding >= the + focus outline extent so link outlines and pills aren't cut off */ + padding: 1.5rem 0.5rem 2rem; border-right: 1px solid var(--border); } @@ -838,6 +925,33 @@ button { font-weight: 600; } +/* Free editor is not a progress-tracked chapter, so it drops the ring/check + gutter and reads as a distinct chip pinned above the chapter groups. */ +.nav-group a.fe-pill { + display: flex; + align-items: center; + gap: 0.5rem; + margin: 0 0.25rem 0.25rem; + padding: 0.5rem 0.75rem; + border: 1px solid var(--border); + border-radius: 8px; + background: var(--bg-soft); + color: var(--text); + font-weight: 600; +} + +.nav-group a.fe-pill:hover, +.nav-group a.fe-pill.is-current { + border-color: var(--accent); + background: var(--accent-soft); + color: var(--accent-strong); +} + +.fe-ico { + color: var(--accent); + font-weight: 700; +} + .sidebar-backdrop { display: none; } @@ -1182,7 +1296,8 @@ h3:hover .heading-anchor, } @media (max-width: 860px) { - .doc-layout { + .doc-layout, + .tutorial-layout { grid-template-columns: minmax(0, 1fr); } @@ -1234,3 +1349,809 @@ h3:hover .heading-anchor, display: none; } } + +/* ---------- tutorial (/learn/) ---------- */ + +/* compact CTA variant of .btn-primary for the top bar */ +.btn-cta { + padding: 0.3rem 0.85rem; + margin-right: 0.5rem; + border-radius: 6px; + font-size: 0.85rem; + white-space: nowrap; +} + +.tutorial-layout { + max-width: 90rem; + margin: 0 auto; + display: grid; + grid-template-columns: 16rem minmax(0, 1fr); + gap: 2rem; + padding: 0 1rem; +} + +.tutorial-main { + padding: 1.5rem 0 3rem; + min-width: 0; +} + +.tutorial-head h1 { + font-size: clamp(1.6rem, 3vw, 2.1rem); + margin: 0 0 0.5rem; + letter-spacing: -0.01em; +} + +.ch-kicker { + margin: 0 0 0.25rem; + font-size: 0.8rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.06em; + color: var(--accent-strong); +} + +.ch-intro { + color: var(--muted); + max-width: 56rem; + margin: 0 0 0.5rem; +} + +.ch-docs { + font-size: 0.9rem; + color: var(--muted); + margin: 0 0 1.25rem; +} + +/* live head only: docs links left, "Help me" right (the fallback keeps the plain paragraph) */ + +.ch-docs-row { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: 0.5rem 1.5rem; + margin: 0 0 1.25rem; +} + +.ch-docs-row .ch-docs { + margin: 0; +} + +.ch-docs-row .btn { + margin-left: auto; + padding: 0.35rem 0.9rem; + font-size: 0.85rem; +} + +.ch-docs-row .btn[hidden] { + display: none; +} + +/* step accordion between the intro and the IDE */ + +.step-list { + margin: 0 0 1rem; +} + +.step-list[hidden] { + display: none; +} + +.step-list ol { + list-style: none; + margin: 0; + padding: 0; + border: 1px solid var(--border); + border-radius: 8px; + background: var(--bg-raised); + overflow: hidden; +} + +.step-list li + li { + border-top: 1px solid var(--border); +} + +.step-list li.is-current { + background: color-mix(in srgb, var(--accent) 7%, transparent); +} + +.step-list summary { + display: flex; + align-items: baseline; + gap: 0.4rem; + padding: 0.5rem 0.9rem; + font-size: 0.9rem; + font-weight: 600; + cursor: pointer; + list-style: none; +} + +.step-list summary::-webkit-details-marker { + display: none; +} + +.step-list li.is-done summary { + color: var(--muted); + font-weight: 400; +} + +.step-mark { + display: inline-block; + width: 1.1rem; + color: #3fb950; + font-weight: 700; + flex: none; +} + +.step-list li.is-done .step-mark::before { + content: '✓'; +} + +.step-list li.is-assisted .step-mark { + color: var(--accent); /* step cleared with an assist */ +} + +.step-explain { + margin: 0; + padding: 0 0.9rem 0.65rem 2.4rem; + font-size: 0.9rem; + color: var(--muted); + max-width: 56rem; +} + +.fallback-steps li { + margin: 0.35rem 0; +} + +/* chapter rail marks */ + +/* per-chapter step progress: an SVG donut with one arc per step (see + ringSvg in tutorial.js); solved arcs draw bold in the text color */ + +.ch-ring { + display: inline-block; + width: 1.3rem; +} + +/* the completion check takes the ring's slot once a chapter is done */ +.ch-ring[hidden] { + display: none; +} + +.ch-ring svg { + width: 0.85rem; + height: 0.85rem; + vertical-align: -0.1rem; +} + +.ch-ring .seg { + fill: none; + stroke: var(--muted); + stroke-opacity: 0.4; + stroke-width: 1.5; +} + +.ch-ring .seg.is-done { + stroke: #3fb950; /* solved by the user */ + stroke-opacity: 1; + stroke-width: 3; +} + +.ch-ring .seg.is-done.is-assisted { + stroke: var(--accent); /* solved with an assist */ +} + +.ch-mark { + display: inline-block; + width: 1.3rem; + color: #3fb950; + font-weight: 700; +} + +/* only a real completion mark occupies the slot; otherwise the ring shows */ +.ch-mark:not(.is-done):not(.is-assisted) { + display: none; +} + +.ch-mark.is-done::before { + content: '✓'; +} + +.ch-mark.is-assisted::before { + content: '✓'; + color: var(--accent); +} + +.rail-foot { + margin-top: 1.5rem; + padding: 0.75rem 0.75rem 0; + border-top: 1px solid var(--border); +} + +.rail-legend { + font-size: 0.75rem; + color: var(--muted); + margin: 0 0 0.5rem; +} + +.rail-reset { + border: 1px solid var(--border); + background: var(--bg-raised); + color: var(--muted); + border-radius: 6px; + padding: 0.25rem 0.7rem; + font-size: 0.8rem; + cursor: pointer; +} + +.rail-reset:hover { + color: var(--text); + border-color: var(--accent); +} + +/* ide chrome extras */ + +.ide-reset { + margin-left: auto; + border: 1px solid #44403c; + background: #2a2724; + color: #d4d4d4; + border-radius: 6px; + padding: 0.15rem 0.6rem; + font-size: 0.72rem; + cursor: pointer; +} + +.ide-reset:hover { + border-color: var(--accent); +} + +.term-cmd { + display: inline-flex; + align-items: baseline; + flex: 1; + min-width: 0; + margin-left: 0.75rem; + gap: 0; +} + +.argv-input { + flex: 1; + min-width: 4rem; + margin-left: 0.4rem; + border: none; + border-bottom: 1px dashed #44403c; + background: transparent; + color: #d4d4d4; + font-family: ui-monospace, 'Cascadia Code', 'Segoe UI Mono', Menlo, Consolas, monospace; + font-size: 0.75rem; + padding: 0 0.2rem; +} + +.argv-input:focus-visible { + outline: none; + border-bottom-color: var(--accent); +} + +/* assist bar */ + +.assist-bar { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: 0.5rem 1.5rem; + margin-top: 0.9rem; +} + +/* display: flex would beat the UA [hidden] rule (free-editor mode hides the bar) */ +.assist-bar[hidden] { + display: none; +} + +.assist-goal { + margin: 0; + color: var(--text); + font-size: 0.95rem; +} + +.assist-progress { + margin: 0; + color: var(--muted); + font-size: 0.9rem; +} + +/* assist spotlight + popup (inside the IDE, which clips the dim shadow) */ + +.ide-lg { + position: relative; +} + +.spotlight { + position: absolute; + inset: 0; + z-index: 5; +} + +.spotlight-hole { + position: absolute; + border-radius: 5px; + box-shadow: 0 0 0 9999px rgb(0 0 0 / 0.55); + outline: 1px solid color-mix(in srgb, var(--accent) 70%, transparent); + pointer-events: none; +} + +.assist-pop { + position: absolute; + z-index: 6; + max-width: 22rem; + padding: 0.9rem 1rem; + border: 1px solid var(--accent); + border-radius: 8px; + background: #26221f; + color: #e7e5e4; + box-shadow: var(--shadow); + font-size: 0.88rem; + line-height: 1.5; +} + +.assist-pop:focus-visible { + outline: 2px solid var(--accent); +} + +.assist-text { + margin: 0 1.25rem 0.5rem 0; +} + +.assist-doc-link { + margin: 0; + font-size: 0.8rem; +} + +.assist-doc-link a { + /* the popup sits in the always-dark IDE - fix the accent to the dark value */ + color: #f9c21d; +} + +.assist-close { + position: absolute; + top: 0.4rem; + right: 0.4rem; + border: none; + background: transparent; + color: #a8a29e; + font-size: 0.85rem; + cursor: pointer; + padding: 0.15rem 0.35rem; + border-radius: 4px; +} + +.assist-close:hover { + color: #e7e5e4; + background: rgb(255 255 255 / 0.08); +} + +/* follow-up action inside the always-dark popup - fixed dark-theme colors */ + +.assist-auto { + margin-top: 0.7rem; + padding: 0.35rem 0.85rem; + border: 1px solid #57534e; + border-radius: 8px; + background: #2a2724; + color: #d4d4d4; + font-size: 0.82rem; + font-weight: 600; + cursor: pointer; +} + +.assist-auto:hover { + border-color: var(--accent); +} + +/* completed-chapter overlay: the solved IDE stays visible but blurred */ + +.done-overlay { + position: absolute; + inset: 0; + z-index: 7; + display: flex; + align-items: center; + justify-content: center; + padding: 1rem; + background: rgb(20 18 16 / 0.35); + backdrop-filter: blur(5px); + -webkit-backdrop-filter: blur(5px); +} + +/* display: flex would beat the UA [hidden] rule */ +.done-overlay[hidden] { + display: none; +} + +.done-card { + max-width: 24rem; + padding: 1.6rem 2rem; + border: 1px solid #44403c; + border-radius: 10px; + background: #26221f; + color: #e7e5e4; + box-shadow: var(--shadow); + text-align: center; +} + +.done-check { + display: inline-flex; + align-items: center; + justify-content: center; + width: 2.6rem; + height: 2.6rem; + border-radius: 50%; + background: #3fb950; + color: #1e1e1e; + font-size: 1.5rem; + font-weight: 700; +} + +.done-title { + margin: 0.75rem 0 0.25rem; + font-size: 1.1rem; + font-weight: 650; +} + +.done-text { + margin: 0 0 1rem; + font-size: 0.9rem; + color: #a8a29e; +} + +.done-actions { + display: flex; + flex-wrap: wrap; + gap: 0.5rem; + justify-content: center; +} + +/* the card sits in the always-dark IDE - fix the button to dark values */ +.done-card .btn-secondary { + border-color: #57534e; + background: #2a2724; + color: #d4d4d4; + font-size: 0.85rem; + padding: 0.45rem 1rem; +} + +.done-card .btn-secondary:hover { + border-color: var(--accent); + background: #2a2724; +} + +/* resume modal */ + +.resume-modal { + border: 1px solid var(--border); + border-radius: 10px; + background: var(--bg-raised); + color: var(--text); + padding: 1.5rem; + max-width: 26rem; + box-shadow: var(--shadow); +} + +.resume-modal::backdrop { + background: rgb(0 0 0 / 0.45); +} + +.resume-modal h2 { + margin: 0 0 0.5rem; + font-size: 1.15rem; +} + +.resume-modal p { + margin: 0 0 0.75rem; + color: var(--muted); +} + +.resume-note { + color: var(--accent-strong) !important; + font-size: 0.9rem; +} + +.resume-actions { + display: flex; + flex-wrap: wrap; + gap: 0.75rem; + margin-top: 1rem; +} + +/* file dialogs (new file / delete file) */ + +/* fixed width so the modal doesn't grow when the error line appears */ +.file-modal { + width: min(24rem, calc(100vw - 2rem)); +} + +.file-modal .file-fields { + display: grid; + grid-template-columns: auto 1fr; + gap: 0.6rem 0.75rem; + align-items: center; + margin-top: 1rem; +} + +.file-modal label { + font-size: 0.85rem; + color: var(--muted); +} + +.file-modal input { + min-width: 0; + padding: 0.4rem 0.6rem; + border: 1px solid var(--border); + border-radius: 6px; + background: var(--bg); + color: var(--text); + font-family: ui-monospace, Consolas, monospace; + font-size: 0.85rem; +} + +.file-modal input:focus-visible { + outline: none; + border-color: var(--accent); +} + +/* the generic .resume-modal p rule would win on color */ +.file-error { + margin-top: 0.9rem; + color: var(--accent-strong) !important; + font-size: 0.8rem; + line-height: 1.4; +} + +/* no-JS fallback */ + +.tutorial-fallback { + margin-top: 2.5rem; + padding-top: 1.5rem; + border-top: 1px solid var(--border); +} + +.tutorial-fallback h2 { + font-size: 1.3rem; + margin: 0 0 0.5rem; +} + +.tutorial-fallback > p { + color: var(--muted); + max-width: 56rem; +} + +.tutorial-fallback .ex-files { + margin: 1rem 0; +} + +.tutorial-fallback .mini-window.term { + margin-bottom: 1rem; +} + +.tutorial-fallback details { + margin-bottom: 1rem; +} + +.tutorial-fallback summary { + cursor: pointer; + color: var(--link); + margin-bottom: 0.5rem; +} + +/* the large IDE: hero .ide-mock visuals, sized as the page's centerpiece */ +.ide-lg .ide-panes { + align-items: stretch; +} + +.editor { + display: block; + width: 100%; + min-height: 22rem; + margin: 0; + padding: 0.9rem 1rem; + border: 0; + border-top: 1px solid #33302c; + border-radius: 0; + resize: vertical; + background: var(--code-bg); + color: var(--code-text); + font-family: ui-monospace, 'Cascadia Code', 'Segoe UI Mono', Menlo, Consolas, monospace; + font-size: 0.85rem; + line-height: 1.6; + white-space: pre; + tab-size: 2; + caret-color: var(--accent); +} + +.editor:focus-visible { + outline: none; + box-shadow: inset 0 0 0 2px color-mix(in srgb, var(--accent) 45%, transparent); +} + +/* highlight overlay: transparent textarea over an identical-metrics ; + built by tutorial.js, so the no-JS page keeps plain visible textareas */ + +.editor-wrap { + position: relative; + border-top: 1px solid #33302c; +} + +.editor-wrap .editor { + position: relative; + z-index: 1; + border-top: none; + background: transparent; + color: transparent; +} + +.editor-overlaid::selection { + background: rgb(86 156 214 / 0.35); + color: transparent; +} + +.editor-highlight { + position: absolute; + inset: 0; + margin: 0; + padding: 0.9rem 1rem; + overflow: hidden; + background: var(--code-bg); + color: var(--code-text); + font-family: ui-monospace, 'Cascadia Code', 'Segoe UI Mono', Menlo, Consolas, monospace; + font-size: 0.85rem; + line-height: 1.6; + white-space: pre; + tab-size: 2; +} + +/* the base `code { font-size: 0.9em }` shrinks the highlight text below the + textarea's, desyncing glyph widths and drifting the caret rightwards */ +.editor-highlight code { + font: inherit; +} + +/* pane tab strips: one file list per pane - click to switch, ✕ to delete, + + to add; locked chapters show padlocks and a disabled + instead */ + +.pane-tabs { + display: flex; + align-items: stretch; + overflow-x: auto; + background: #191715; +} + +.pane-tabs::-webkit-scrollbar { + height: 6px; +} + +.pane-tabs::-webkit-scrollbar-thumb { + border-width: 2px; +} + +.pane-tabs .pane-tab { + display: inline-flex; + align-items: center; + flex: none; + padding: 0; + color: #8b8b8b; + background: transparent; + border-bottom: 2px solid transparent; +} + +.pane-tabs .pane-tab.is-active { + color: #d4d4d4; + background: #1e1e1e; + border-bottom-color: var(--accent); +} + +.tab-name { + padding: 0.35rem 0.5rem 0.35rem 1rem; + border: 0; + background: none; + color: inherit; + font: inherit; + white-space: nowrap; + cursor: pointer; +} + +.tab-name:last-child { + padding-right: 1rem; +} + +.pane-tab:not(.is-active) .tab-name:hover { + color: #d4d4d4; +} + +.tab-close { + flex: none; + margin-right: 0.45rem; + padding: 0.2rem 0.3rem; + border: 0; + border-radius: 4px; + background: none; + color: #6b6762; + font: inherit; + font-size: 0.65rem; + line-height: 1; + cursor: pointer; +} + +.tab-close:hover { + color: #e7e5e4; + background: #33302c; +} + +.tab-lock { + flex: none; + width: 0.6rem; + height: 0.6rem; + margin-right: 0.7rem; + background: currentColor; + -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Cpath d='M3.5 5V3.5a2.5 2.5 0 0 1 5 0V5H9a1 1 0 0 1 1 1v4a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V6a1 1 0 0 1 1-1h.5Zm1.2 0h2.6V3.5a1.3 1.3 0 0 0-2.6 0V5Z'/%3E%3C/svg%3E") center / contain no-repeat; + mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Cpath d='M3.5 5V3.5a2.5 2.5 0 0 1 5 0V5H9a1 1 0 0 1 1 1v4a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V6a1 1 0 0 1 1-1h.5Zm1.2 0h2.6V3.5a1.3 1.3 0 0 0-2.6 0V5Z'/%3E%3C/svg%3E") center / contain no-repeat; +} + +.tab-add { + flex: none; + padding: 0.25rem 0.7rem; + border: 0; + background: none; + color: #8b8b8b; + font: inherit; + font-family: ui-monospace, Consolas, monospace; + font-size: 0.85rem; + cursor: pointer; +} + +.tab-add:hover:not(:disabled) { + color: var(--accent); +} + +.tab-add:disabled { + color: #55524e; + cursor: not-allowed; +} + +.ide-lg .term-lg { + min-height: 11rem; + max-height: 22rem; + overflow: auto; +} + +.run-btn { + margin-left: auto; + border: 1px solid transparent; + border-radius: 6px; + padding: 0.2rem 0.85rem; + background: var(--accent); + color: #1e1e1e; + font-size: 0.8rem; + font-weight: 650; + cursor: pointer; +} + +.run-btn:hover { + filter: brightness(1.06); +} + +.run-btn:disabled { + opacity: 0.55; + cursor: default; + filter: none; +} + +.tutorial-nojs { + margin: 1.5rem auto 0; + max-width: 56rem; + color: var(--muted); +} + +@media (max-width: 700px) { + .editor { + min-height: 14rem; + } +} diff --git a/src/tutorial.mjs b/src/tutorial.mjs new file mode 100644 index 0000000..1fd5656 --- /dev/null +++ b/src/tutorial.mjs @@ -0,0 +1,300 @@ +// The /learn/ page: chapter rail + a large editable IDE mock whose terminal +// executes the real flashtrace release build in a module worker (see +// src/scripts/tutorial.js). Server-renders chapter 1 as the initial state and +// a full read-only fallback for browsers without JavaScript. Internal naming +// is `tutorial` throughout - the public button label is swappable without +// touching code or storage keys. +import { chapters } from './tutorial/chapters.mjs'; +import { chapterPayload } from './tutorial/verify.mjs'; +import { esc, GITHUB_URL, highlightTokens, pageShell } from './layout.mjs'; +import { colorizeReport } from './report-colors.mjs'; + +const LANG = 'js'; + +const dots = ``; + +function docsLinks(chapter) { + return chapter.docs + .map((d) => `${esc(d.label)}`) + .join(' · '); +} + +function chapterRail() { + const groups = []; + for (const chapter of chapters) { + let group = groups.find((g) => g.label === chapter.group); + if (!group) { + group = { label: chapter.group, items: [] }; + groups.push(group); + } + group.items.push(chapter); + } + let no = 0; + const groupHtml = groups + .map( + (g) => ` + ${esc(g.label)} + + ${g.items + .map((ch) => { + no += 1; + return `${no} · ${esc(ch.title)}`; + }) + .join('\n ')} + +`, + ) + .join('\n'); + return ` + + + ‹›Free editor + + +${groupHtml} + + steps solved · completed · with assists + Reset progress + + +`; +} + +export const LOCK_TIP = 'This chapter does not allow file management'; + +// Server-rendered initial tab strip (chapter 1); tutorial.js re-renders it on +// every chapter switch and tab operation with the same structure. +function paneTabs(pane, fileName, locked, label) { + const lock = locked ? `` : ''; + const addAttrs = locked ? ` disabled title="${LOCK_TIP}"` : ' title="New file"'; + return ` + ${esc(fileName)}${lock} + + + `; +} + +function ide(first) { + const variant = first.variants[LANG]; + return ` + + ${dots} + chapter 1 · ${esc(first.title)} + Reset files + + + + ${paneTabs('spec', first.spec.file, first.locked, 'Spec files')} + ${esc(first.spec.body)} + + + ${paneTabs('code', variant.file, first.locked, 'Code files')} + ${esc(variant.body)} + + + + + terminal + $ npx flashtrace + ▶ Run + + press Run to trace the project + + + + ✓ + Chapter complete + + + View + Reset chapter + + + + + + ✕ + + Read more in the docs + Do this step for me + +`; +} + +// Step accordion between the chapter intro and the IDE: one per +// step, the current one unfolded, finished ones greyed out with a check. +// Server-renders chapter 1's start state (step 1 current); tutorial.js +// re-renders the items on every chapter switch and re-syncs the open/done +// state after every run with the same structure. +function stepListItems(steps, currentIndex) { + return steps + .map((step, i) => { + let state = ''; + if (i < currentIndex) state = ' class="is-done"'; + else if (i === currentIndex) state = ' class="is-current"'; + return ` + ${i + 1} · ${esc(step.title)} + ${esc(step.explain)} +`; + }) + .join('\n'); +} + +function stepList(first) { + return ` + +${stepListItems(first.steps, 0)} + +`; +} + +function resumeDialog() { + return ` + Work in progress + You have unsaved work in this chapter - resume it, or start fresh? + This chapter has been updated since you last worked on it. + + Resume + Start fresh + +`; +} + +// Datalists double as the single client-side source of the supported +// extensions: the pickers autocomplete from them and tutorial.js validates +// against them. The code list is parsed from docs/code-tags.md at build time; +// the spec list mirrors what analyzeBuffers routes to parseMarkdown. +function fileDialogs(codeExtensions) { + const specExtensions = ['.md', '.markdown']; + const options = (exts) => exts.map((e) => ``).join(''); + return `${options(specExtensions)} +${options(codeExtensions)} + + New file + + Name + + Type + + + Open an issue to ask for it? + + Create + Cancel + + + + Delete file + + + Delete + Cancel + +`; +} + +// Shown when someone lands on #editor without any completed chapter: offer +// the guided route before leaving a newcomer alone with two empty files. +function welcomeDialog() { + return ` + First time with flashtrace? + This is the free editor - a blank project running the real tool. The chapters on the left teach flashtrace hands-on, a few minutes each. + + Start learning from the first chapter + Open the free editor + +`; +} + +function miniWindow(name, inner, term = false) { + return `${dots}${esc(name)}${inner}`; +} + +// Read-only chapter rendering for browsers without JavaScript: the inputs and +// the build-time captured real runs, at the fidelity of the landing examples. +function fallbackChapters(verified) { + const sections = chapters + .map((chapter, index) => { + const variant = chapter.variants[LANG]; + const captured = verified[chapter.id]; + const cmd = ['npx flashtrace', ...chapter.argv].join(' '); + const startTerm = + `$ ${esc(cmd)}\n` + + colorizeReport(captured.startOutput) + + `\nexit ${captured.startExit}`; + const solvedTerm = + `$ ${esc(cmd)}\n` + + colorizeReport(captured.solvedOutput) + + `\nexit ${captured.solvedExit}`; + return ` + ${index + 1} · ${esc(chapter.title)} + ${esc(chapter.intro)} + + ${chapter.steps.map((step) => `${esc(step.title)}. ${esc(step.explain)}`).join('\n ')} + + + ${miniWindow(chapter.spec.file, highlightTokens(esc(chapter.spec.body)))} + ${chapter.noCode ? '' : miniWindow(variant.file, highlightTokens(esc(variant.body)))} + + ${miniWindow('terminal', startTerm, true)} + + The solved run + ${miniWindow('terminal', solvedTerm, true)} + + Read more: ${docsLinks(chapter)} +`; + }) + .join('\n'); + return ` + +The interactive editor needs JavaScript. Below are all chapters read-only, with their inputs and real captured runs. +${sections} +`; +} + +export function renderTutorial({ version, verified, codeExtensions }) { + const first = chapters[0]; + const payloads = chapters.map((chapter) => ({ + ...chapterPayload(chapter, LANG), + rev: verified[chapter.id].rev, + })); + const dataJson = JSON.stringify({ v: 1, lang: LANG, chapters: payloads }).replace(/ +${chapterRail()} + + + Chapter 1 · ${esc(first.group)} + ${esc(first.title)} + ${esc(first.intro)} + + Read more: ${docsLinks(first)} + Help me + + +${stepList(first)} +${ide(first)} + + Goal: ${esc(first.goal)} + Run to check your progress. + +${resumeDialog()} +${welcomeDialog()} +${fileDialogs(codeExtensions)} +${fallbackChapters(verified)} + + + +
' + esc(step.explain) + '
; + built by tutorial.js, so the no-JS page keeps plain visible textareas */ + +.editor-wrap { + position: relative; + border-top: 1px solid #33302c; +} + +.editor-wrap .editor { + position: relative; + z-index: 1; + border-top: none; + background: transparent; + color: transparent; +} + +.editor-overlaid::selection { + background: rgb(86 156 214 / 0.35); + color: transparent; +} + +.editor-highlight { + position: absolute; + inset: 0; + margin: 0; + padding: 0.9rem 1rem; + overflow: hidden; + background: var(--code-bg); + color: var(--code-text); + font-family: ui-monospace, 'Cascadia Code', 'Segoe UI Mono', Menlo, Consolas, monospace; + font-size: 0.85rem; + line-height: 1.6; + white-space: pre; + tab-size: 2; +} + +/* the base `code { font-size: 0.9em }` shrinks the highlight text below the + textarea's, desyncing glyph widths and drifting the caret rightwards */ +.editor-highlight code { + font: inherit; +} + +/* pane tab strips: one file list per pane - click to switch, ✕ to delete, + + to add; locked chapters show padlocks and a disabled + instead */ + +.pane-tabs { + display: flex; + align-items: stretch; + overflow-x: auto; + background: #191715; +} + +.pane-tabs::-webkit-scrollbar { + height: 6px; +} + +.pane-tabs::-webkit-scrollbar-thumb { + border-width: 2px; +} + +.pane-tabs .pane-tab { + display: inline-flex; + align-items: center; + flex: none; + padding: 0; + color: #8b8b8b; + background: transparent; + border-bottom: 2px solid transparent; +} + +.pane-tabs .pane-tab.is-active { + color: #d4d4d4; + background: #1e1e1e; + border-bottom-color: var(--accent); +} + +.tab-name { + padding: 0.35rem 0.5rem 0.35rem 1rem; + border: 0; + background: none; + color: inherit; + font: inherit; + white-space: nowrap; + cursor: pointer; +} + +.tab-name:last-child { + padding-right: 1rem; +} + +.pane-tab:not(.is-active) .tab-name:hover { + color: #d4d4d4; +} + +.tab-close { + flex: none; + margin-right: 0.45rem; + padding: 0.2rem 0.3rem; + border: 0; + border-radius: 4px; + background: none; + color: #6b6762; + font: inherit; + font-size: 0.65rem; + line-height: 1; + cursor: pointer; +} + +.tab-close:hover { + color: #e7e5e4; + background: #33302c; +} + +.tab-lock { + flex: none; + width: 0.6rem; + height: 0.6rem; + margin-right: 0.7rem; + background: currentColor; + -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Cpath d='M3.5 5V3.5a2.5 2.5 0 0 1 5 0V5H9a1 1 0 0 1 1 1v4a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V6a1 1 0 0 1 1-1h.5Zm1.2 0h2.6V3.5a1.3 1.3 0 0 0-2.6 0V5Z'/%3E%3C/svg%3E") center / contain no-repeat; + mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Cpath d='M3.5 5V3.5a2.5 2.5 0 0 1 5 0V5H9a1 1 0 0 1 1 1v4a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V6a1 1 0 0 1 1-1h.5Zm1.2 0h2.6V3.5a1.3 1.3 0 0 0-2.6 0V5Z'/%3E%3C/svg%3E") center / contain no-repeat; +} + +.tab-add { + flex: none; + padding: 0.25rem 0.7rem; + border: 0; + background: none; + color: #8b8b8b; + font: inherit; + font-family: ui-monospace, Consolas, monospace; + font-size: 0.85rem; + cursor: pointer; +} + +.tab-add:hover:not(:disabled) { + color: var(--accent); +} + +.tab-add:disabled { + color: #55524e; + cursor: not-allowed; +} + +.ide-lg .term-lg { + min-height: 11rem; + max-height: 22rem; + overflow: auto; +} + +.run-btn { + margin-left: auto; + border: 1px solid transparent; + border-radius: 6px; + padding: 0.2rem 0.85rem; + background: var(--accent); + color: #1e1e1e; + font-size: 0.8rem; + font-weight: 650; + cursor: pointer; +} + +.run-btn:hover { + filter: brightness(1.06); +} + +.run-btn:disabled { + opacity: 0.55; + cursor: default; + filter: none; +} + +.tutorial-nojs { + margin: 1.5rem auto 0; + max-width: 56rem; + color: var(--muted); +} + +@media (max-width: 700px) { + .editor { + min-height: 14rem; + } +} diff --git a/src/tutorial.mjs b/src/tutorial.mjs new file mode 100644 index 0000000..1fd5656 --- /dev/null +++ b/src/tutorial.mjs @@ -0,0 +1,300 @@ +// The /learn/ page: chapter rail + a large editable IDE mock whose terminal +// executes the real flashtrace release build in a module worker (see +// src/scripts/tutorial.js). Server-renders chapter 1 as the initial state and +// a full read-only fallback for browsers without JavaScript. Internal naming +// is `tutorial` throughout - the public button label is swappable without +// touching code or storage keys. +import { chapters } from './tutorial/chapters.mjs'; +import { chapterPayload } from './tutorial/verify.mjs'; +import { esc, GITHUB_URL, highlightTokens, pageShell } from './layout.mjs'; +import { colorizeReport } from './report-colors.mjs'; + +const LANG = 'js'; + +const dots = ``; + +function docsLinks(chapter) { + return chapter.docs + .map((d) => `${esc(d.label)}`) + .join(' · '); +} + +function chapterRail() { + const groups = []; + for (const chapter of chapters) { + let group = groups.find((g) => g.label === chapter.group); + if (!group) { + group = { label: chapter.group, items: [] }; + groups.push(group); + } + group.items.push(chapter); + } + let no = 0; + const groupHtml = groups + .map( + (g) => ` + ${esc(g.label)} + + ${g.items + .map((ch) => { + no += 1; + return `${no} · ${esc(ch.title)}`; + }) + .join('\n ')} + +`, + ) + .join('\n'); + return ` + + + ‹›Free editor + + +${groupHtml} + + steps solved · completed · with assists + Reset progress + + +`; +} + +export const LOCK_TIP = 'This chapter does not allow file management'; + +// Server-rendered initial tab strip (chapter 1); tutorial.js re-renders it on +// every chapter switch and tab operation with the same structure. +function paneTabs(pane, fileName, locked, label) { + const lock = locked ? `` : ''; + const addAttrs = locked ? ` disabled title="${LOCK_TIP}"` : ' title="New file"'; + return ` + ${esc(fileName)}${lock} + + + `; +} + +function ide(first) { + const variant = first.variants[LANG]; + return ` + + ${dots} + chapter 1 · ${esc(first.title)} + Reset files + + + + ${paneTabs('spec', first.spec.file, first.locked, 'Spec files')} + ${esc(first.spec.body)} + + + ${paneTabs('code', variant.file, first.locked, 'Code files')} + ${esc(variant.body)} + + + + + terminal + $ npx flashtrace + ▶ Run + + press Run to trace the project + + + + ✓ + Chapter complete + + + View + Reset chapter + + + + + + ✕ + + Read more in the docs + Do this step for me + +`; +} + +// Step accordion between the chapter intro and the IDE: one per +// step, the current one unfolded, finished ones greyed out with a check. +// Server-renders chapter 1's start state (step 1 current); tutorial.js +// re-renders the items on every chapter switch and re-syncs the open/done +// state after every run with the same structure. +function stepListItems(steps, currentIndex) { + return steps + .map((step, i) => { + let state = ''; + if (i < currentIndex) state = ' class="is-done"'; + else if (i === currentIndex) state = ' class="is-current"'; + return ` + ${i + 1} · ${esc(step.title)} + ${esc(step.explain)} +`; + }) + .join('\n'); +} + +function stepList(first) { + return ` + +${stepListItems(first.steps, 0)} + +`; +} + +function resumeDialog() { + return ` + Work in progress + You have unsaved work in this chapter - resume it, or start fresh? + This chapter has been updated since you last worked on it. + + Resume + Start fresh + +`; +} + +// Datalists double as the single client-side source of the supported +// extensions: the pickers autocomplete from them and tutorial.js validates +// against them. The code list is parsed from docs/code-tags.md at build time; +// the spec list mirrors what analyzeBuffers routes to parseMarkdown. +function fileDialogs(codeExtensions) { + const specExtensions = ['.md', '.markdown']; + const options = (exts) => exts.map((e) => ``).join(''); + return `${options(specExtensions)} +${options(codeExtensions)} + + New file + + Name + + Type + + + Open an issue to ask for it? + + Create + Cancel + + + + Delete file + + + Delete + Cancel + +`; +} + +// Shown when someone lands on #editor without any completed chapter: offer +// the guided route before leaving a newcomer alone with two empty files. +function welcomeDialog() { + return ` + First time with flashtrace? + This is the free editor - a blank project running the real tool. The chapters on the left teach flashtrace hands-on, a few minutes each. + + Start learning from the first chapter + Open the free editor + +`; +} + +function miniWindow(name, inner, term = false) { + return `${dots}${esc(name)}${inner}`; +} + +// Read-only chapter rendering for browsers without JavaScript: the inputs and +// the build-time captured real runs, at the fidelity of the landing examples. +function fallbackChapters(verified) { + const sections = chapters + .map((chapter, index) => { + const variant = chapter.variants[LANG]; + const captured = verified[chapter.id]; + const cmd = ['npx flashtrace', ...chapter.argv].join(' '); + const startTerm = + `$ ${esc(cmd)}\n` + + colorizeReport(captured.startOutput) + + `\nexit ${captured.startExit}`; + const solvedTerm = + `$ ${esc(cmd)}\n` + + colorizeReport(captured.solvedOutput) + + `\nexit ${captured.solvedExit}`; + return ` + ${index + 1} · ${esc(chapter.title)} + ${esc(chapter.intro)} + + ${chapter.steps.map((step) => `${esc(step.title)}. ${esc(step.explain)}`).join('\n ')} + + + ${miniWindow(chapter.spec.file, highlightTokens(esc(chapter.spec.body)))} + ${chapter.noCode ? '' : miniWindow(variant.file, highlightTokens(esc(variant.body)))} + + ${miniWindow('terminal', startTerm, true)} + + The solved run + ${miniWindow('terminal', solvedTerm, true)} + + Read more: ${docsLinks(chapter)} +`; + }) + .join('\n'); + return ` + +The interactive editor needs JavaScript. Below are all chapters read-only, with their inputs and real captured runs. +${sections} +`; +} + +export function renderTutorial({ version, verified, codeExtensions }) { + const first = chapters[0]; + const payloads = chapters.map((chapter) => ({ + ...chapterPayload(chapter, LANG), + rev: verified[chapter.id].rev, + })); + const dataJson = JSON.stringify({ v: 1, lang: LANG, chapters: payloads }).replace(/ +${chapterRail()} + + + Chapter 1 · ${esc(first.group)} + ${esc(first.title)} + ${esc(first.intro)} + + Read more: ${docsLinks(first)} + Help me + + +${stepList(first)} +${ide(first)} + + Goal: ${esc(first.goal)} + Run to check your progress. + +${resumeDialog()} +${welcomeDialog()} +${fileDialogs(codeExtensions)} +${fallbackChapters(verified)} + + + +
${esc(g.label)}
steps solved · completed · with assists
press Run to trace the project
Chapter complete
Read more in the docs
${esc(step.explain)}
You have unsaved work in this chapter - resume it, or start fresh?
This chapter has been updated since you last worked on it.
Open an issue to ask for it?
This is the free editor - a blank project running the real tool. The chapters on the left teach flashtrace hands-on, a few minutes each.
${inner}
${esc(chapter.intro)}
Read more: ${docsLinks(chapter)}
The interactive editor needs JavaScript. Below are all chapters read-only, with their inputs and real captured runs.
Chapter 1 · ${esc(first.group)}
${esc(first.intro)}
Read more: ${docsLinks(first)}
Goal: ${esc(first.goal)}
Run to check your progress.