dsh-aha-tutor 1.6.0 → 1.7.0

package/lib/{runtime-B6zUpJjA.js → runtime-DfoeKFPj.js}

@@ -826,6 +826,13 @@ function normalizeConcepts(raw, fallbackName) {
 function keepId(value, prefix) {
 	return typeof value === "string" && new RegExp(`^${prefix}_[a-z0-9]{6,40}$`, "u").test(value) ? value : newId(prefix);
 }
+const LESSON_DEPTHS = Object.freeze([
+	"intuition",
+	"definition",
+	"derivation",
+	"application",
+	"extension"
+]);
 function normalizeLesson(raw) {
 	const title = text(raw?.title, 120);
 	if (!title) return null;
@@ -841,7 +848,8 @@ function normalizeLesson(raw) {
 			"remedial",
 			"review",
 			"challenge"
-		].includes(raw?.kind) ? raw.kind : "lesson"
+		].includes(raw?.kind) ? raw.kind : "lesson",
+		...LESSON_DEPTHS.includes(raw?.depth) ? { depth: raw.depth } : {}
 	};
 }
 function normalizeUnits(rawUnits) {
@@ -1044,6 +1052,49 @@ function normalizePractice(raw, conceptIds = []) {
 		id: `i${index + 1}`
 	})) };
 }
+function normalizeHandout(raw) {
+	const points = list(raw?.points ?? raw?.keyPoints, 6, (point) => {
+		const title = text(typeof point === "string" ? point : point?.title ?? point?.point, 160);
+		return title ? {
+			title,
+			oneLine: text(point?.oneLine ?? point?.summary, 300),
+			detail: text(point?.detail, 600)
+		} : null;
+	});
+	if (!points.length) throw new Error("the handout has no key points");
+	const example = raw?.example && typeof raw.example === "object" ? {
+		problem: text(raw.example.problem ?? raw.example.question, 800),
+		steps: strings(raw.example.steps, 10, 400),
+		answer: text(raw.example.answer, 300)
+	} : null;
+	return {
+		title: text(raw?.title, 160),
+		summary: text(raw?.summary ?? raw?.overview, 800),
+		points,
+		example: example?.problem ? example : null,
+		mistakes: list(raw?.mistakes, 5, (item) => {
+			const mistake = text(typeof item === "string" ? item : item?.mistake, 300);
+			return mistake ? {
+				mistake,
+				fix: text(item?.fix ?? item?.instead, 300)
+			} : null;
+		}),
+		glossary: list(raw?.glossary, 10, (item) => {
+			const term = text(item?.term, 80);
+			return term ? {
+				term,
+				meaning: text(item?.meaning ?? item?.definition, 300)
+			} : null;
+		}),
+		questions: list(raw?.questions ?? raw?.selfCheck, 5, (item) => {
+			const question = text(typeof item === "string" ? item : item?.question, 400);
+			return question ? {
+				question,
+				answer: text(item?.answer, 400)
+			} : null;
+		})
+	};
+}
 function normalizeCards(raw) {
 	return list(raw?.cards ?? raw, LIMITS.cards, (card, index) => {
 		const front = text(card?.front ?? card?.q ?? card?.question, 600);
@@ -1662,6 +1713,171 @@ function parseJsonLines(raw, { final = true } = {}) {
 	};
 }
 //#endregion
+//#region src/core/retrieval.js
+const CJK_RUN = /[぀-ヿ㐀-䶿一-鿿가-힯]+/gu;
+const WORD = /[\p{L}\p{N}][\p{L}\p{N}'_-]*/gu;
+const STOP = /* @__PURE__ */ new Set([
+	"the",
+	"a",
+	"an",
+	"and",
+	"or",
+	"of",
+	"to",
+	"in",
+	"on",
+	"for",
+	"is",
+	"are",
+	"was",
+	"be",
+	"with",
+	"as",
+	"by",
+	"at",
+	"it",
+	"this",
+	"that",
+	"from"
+]);
+function tokenize(value) {
+	const textValue = String(value ?? "").toLowerCase();
+	const tokens = [];
+	for (const run of textValue.match(CJK_RUN) ?? []) {
+		if (run.length === 1) tokens.push(run);
+		for (let index = 0; index < run.length - 1; index += 1) tokens.push(run.slice(index, index + 2));
+	}
+	for (const word of textValue.replace(CJK_RUN, " ").match(WORD) ?? []) if (word.length > 1 && !STOP.has(word)) tokens.push(word);
+	return tokens;
+}
+function buildIndex(chunks) {
+	const docs = chunks.map((chunk) => {
+		const counts = /* @__PURE__ */ new Map();
+		const tokens = tokenize(chunk.text);
+		for (const token of tokens) counts.set(token, (counts.get(token) ?? 0) + 1);
+		return {
+			chunk,
+			counts,
+			length: tokens.length
+		};
+	});
+	const df = /* @__PURE__ */ new Map();
+	for (const doc of docs) for (const token of doc.counts.keys()) df.set(token, (df.get(token) ?? 0) + 1);
+	return {
+		docs,
+		df,
+		avg: docs.reduce((sum, doc) => sum + doc.length, 0) / Math.max(1, docs.length)
+	};
+}
+function search(index, query, { limit = 6, k1 = 1.4, b = .75 } = {}) {
+	const terms = [...new Set(tokenize(query))];
+	if (!terms.length || !index.docs.length) return [];
+	const total = index.docs.length;
+	return index.docs.map((doc) => {
+		let score = 0;
+		for (const term of terms) {
+			const tf = doc.counts.get(term);
+			if (!tf) continue;
+			const df = index.df.get(term) ?? 0;
+			const idf = Math.log(1 + (total - df + .5) / (df + .5));
+			score += idf * (tf * (k1 + 1) / (tf + k1 * (1 - b + b * (doc.length / (index.avg || 1)))));
+		}
+		return {
+			chunk: doc.chunk,
+			score
+		};
+	}).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
+}
+function selectPassages(chunks, query, { maxChars = 12e3, limit = 12 } = {}) {
+	if (!chunks?.length) return [];
+	const picked = query ? search(buildIndex(chunks), query, { limit }).map((entry) => entry.chunk) : chunks.slice(0, limit);
+	const result = [];
+	let used = 0;
+	for (const chunk of picked) {
+		if (used + chunk.text.length > maxChars) {
+			const room = maxChars - used;
+			if (room > 400) result.push({
+				...chunk,
+				text: `${chunk.text.slice(0, room)}…`
+			});
+			break;
+		}
+		result.push(chunk);
+		used += chunk.text.length;
+	}
+	return result;
+}
+function spreadPassages(chunks, { maxChars = 12e3, samples = 16 } = {}) {
+	if (!chunks?.length) return [];
+	if (chunks.reduce((sum, chunk) => sum + chunk.text.length, 0) <= maxChars) return chunks.slice();
+	const count = Math.min(chunks.length, Math.max(2, samples));
+	const share = Math.max(200, Math.floor(maxChars / count));
+	const picked = [];
+	for (let index = 0; index < count; index += 1) {
+		const at = Math.round(index * (chunks.length - 1) / (count - 1));
+		if (picked.at(-1) !== at) picked.push(at);
+	}
+	return picked.map((at) => {
+		const chunk = chunks[at];
+		return chunk.text.length > share ? {
+			...chunk,
+			text: `${chunk.text.slice(0, share)}…`
+		} : chunk;
+	});
+}
+function documentParts(chunks, { partChars = 2e4, maxParts = 24, maxPartChars = 4e4 } = {}) {
+	if (!chunks?.length) return [];
+	const total = Math.max(1, chunks.reduce((sum, chunk) => sum + chunk.text.length, 0));
+	const count = Math.min(maxParts, Math.max(1, Math.ceil(total / partChars)));
+	const parts = Array.from({ length: count }, () => []);
+	let seen = 0;
+	for (const chunk of chunks) {
+		parts[Math.min(count - 1, Math.floor(seen / total * count))].push(chunk);
+		seen += chunk.text.length;
+	}
+	return parts.filter((part) => part.length).map((part) => {
+		return part.reduce((sum, chunk) => sum + chunk.text.length, 0) > maxPartChars ? spreadPassages(part, {
+			maxChars: maxPartChars,
+			samples: 24
+		}) : part;
+	});
+}
+function locationOf(passage) {
+	return passage?.page ? `p.${passage.page}` : passage?.slide ? `slide ${passage.slide}` : passage?.section ?? "";
+}
+function passageRange(passages) {
+	const first = locationOf(passages?.[0]);
+	const last = locationOf(passages?.at(-1));
+	return first && last && first !== last ? `${first}–${last}` : first || last;
+}
+function formatPassages(passages, sourceTitle) {
+	return passages.map((passage) => {
+		const where = locationOf(passage);
+		return `<<${[sourceTitle ?? passage.source ?? "source", where].filter(Boolean).join(" · ") || "excerpt"}>>\n${passage.text}`;
+	}).join("\n\n");
+}
+function snippetOf(text, query, { width = 140 } = {}) {
+	const value = String(text ?? "").replace(/\*\*|__|`/gu, "").replace(/^#{1,6}\s+/gmu, "").replace(/\s*\|\s*(?:\|\s*)*/gu, " · ").replace(/\s+/gu, " ").replace(/^ · | · $/gu, "").trim();
+	if (value.length <= width) return value;
+	const lower = value.toLowerCase();
+	const terms = [...new Set(tokenize(query))];
+	const hits = [];
+	for (const term of terms) for (let at = lower.indexOf(term); at !== -1 && hits.length < 200; at = lower.indexOf(term, at + term.length)) hits.push(at);
+	if (!hits.length) return `${value.slice(0, width)}…`;
+	hits.sort((a, b) => a - b);
+	let best = hits[0];
+	let bestCount = 0;
+	for (const start of hits) {
+		const count = hits.filter((at) => at >= start && at < start + width).length;
+		if (count > bestCount) {
+			best = start;
+			bestCount = count;
+		}
+	}
+	const from = Math.max(0, Math.min(best - Math.round(width / 4), value.length - width));
+	return `${from > 0 ? "…" : ""}${value.slice(from, from + width)}${from + width < value.length ? "…" : ""}`;
+}
+//#endregion
 //#region src/core/mastery.js
 const BKT_DEFAULTS = Object.freeze({
 	pInit: .2,
@@ -1866,152 +2082,9 @@ function summarizeForPrompt(states, limit = 12) {
 	}));
 }
 //#endregion
-//#region src/core/retrieval.js
-const CJK_RUN = /[぀-ヿ㐀-䶿一-鿿가-힯]+/gu;
-const WORD = /[\p{L}\p{N}][\p{L}\p{N}'_-]*/gu;
-const STOP = /* @__PURE__ */ new Set([
-	"the",
-	"a",
-	"an",
-	"and",
-	"or",
-	"of",
-	"to",
-	"in",
-	"on",
-	"for",
-	"is",
-	"are",
-	"was",
-	"be",
-	"with",
-	"as",
-	"by",
-	"at",
-	"it",
-	"this",
-	"that",
-	"from"
-]);
-function tokenize(value) {
-	const textValue = String(value ?? "").toLowerCase();
-	const tokens = [];
-	for (const run of textValue.match(CJK_RUN) ?? []) {
-		if (run.length === 1) tokens.push(run);
-		for (let index = 0; index < run.length - 1; index += 1) tokens.push(run.slice(index, index + 2));
-	}
-	for (const word of textValue.replace(CJK_RUN, " ").match(WORD) ?? []) if (word.length > 1 && !STOP.has(word)) tokens.push(word);
-	return tokens;
-}
-function buildIndex(chunks) {
-	const docs = chunks.map((chunk) => {
-		const counts = /* @__PURE__ */ new Map();
-		const tokens = tokenize(chunk.text);
-		for (const token of tokens) counts.set(token, (counts.get(token) ?? 0) + 1);
-		return {
-			chunk,
-			counts,
-			length: tokens.length
-		};
-	});
-	const df = /* @__PURE__ */ new Map();
-	for (const doc of docs) for (const token of doc.counts.keys()) df.set(token, (df.get(token) ?? 0) + 1);
-	return {
-		docs,
-		df,
-		avg: docs.reduce((sum, doc) => sum + doc.length, 0) / Math.max(1, docs.length)
-	};
-}
-function search(index, query, { limit = 6, k1 = 1.4, b = .75 } = {}) {
-	const terms = [...new Set(tokenize(query))];
-	if (!terms.length || !index.docs.length) return [];
-	const total = index.docs.length;
-	return index.docs.map((doc) => {
-		let score = 0;
-		for (const term of terms) {
-			const tf = doc.counts.get(term);
-			if (!tf) continue;
-			const df = index.df.get(term) ?? 0;
-			const idf = Math.log(1 + (total - df + .5) / (df + .5));
-			score += idf * (tf * (k1 + 1) / (tf + k1 * (1 - b + b * (doc.length / (index.avg || 1)))));
-		}
-		return {
-			chunk: doc.chunk,
-			score
-		};
-	}).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
-}
-function selectPassages(chunks, query, { maxChars = 12e3, limit = 12 } = {}) {
-	if (!chunks?.length) return [];
-	const picked = query ? search(buildIndex(chunks), query, { limit }).map((entry) => entry.chunk) : chunks.slice(0, limit);
-	const result = [];
-	let used = 0;
-	for (const chunk of picked) {
-		if (used + chunk.text.length > maxChars) {
-			const room = maxChars - used;
-			if (room > 400) result.push({
-				...chunk,
-				text: `${chunk.text.slice(0, room)}…`
-			});
-			break;
-		}
-		result.push(chunk);
-		used += chunk.text.length;
-	}
-	return result;
-}
-function spreadPassages(chunks, { maxChars = 12e3, samples = 16 } = {}) {
-	if (!chunks?.length) return [];
-	if (chunks.reduce((sum, chunk) => sum + chunk.text.length, 0) <= maxChars) return chunks.slice();
-	const count = Math.min(chunks.length, Math.max(2, samples));
-	const share = Math.max(200, Math.floor(maxChars / count));
-	const picked = [];
-	for (let index = 0; index < count; index += 1) {
-		const at = Math.round(index * (chunks.length - 1) / (count - 1));
-		if (picked.at(-1) !== at) picked.push(at);
-	}
-	return picked.map((at) => {
-		const chunk = chunks[at];
-		return chunk.text.length > share ? {
-			...chunk,
-			text: `${chunk.text.slice(0, share)}…`
-		} : chunk;
-	});
-}
-function documentParts(chunks, { partChars = 2e4, maxParts = 24, maxPartChars = 4e4 } = {}) {
-	if (!chunks?.length) return [];
-	const total = Math.max(1, chunks.reduce((sum, chunk) => sum + chunk.text.length, 0));
-	const count = Math.min(maxParts, Math.max(1, Math.ceil(total / partChars)));
-	const parts = Array.from({ length: count }, () => []);
-	let seen = 0;
-	for (const chunk of chunks) {
-		parts[Math.min(count - 1, Math.floor(seen / total * count))].push(chunk);
-		seen += chunk.text.length;
-	}
-	return parts.filter((part) => part.length).map((part) => {
-		return part.reduce((sum, chunk) => sum + chunk.text.length, 0) > maxPartChars ? spreadPassages(part, {
-			maxChars: maxPartChars,
-			samples: 24
-		}) : part;
-	});
-}
-function locationOf(passage) {
-	return passage?.page ? `p.${passage.page}` : passage?.slide ? `slide ${passage.slide}` : passage?.section ?? "";
-}
-function passageRange(passages) {
-	const first = locationOf(passages?.[0]);
-	const last = locationOf(passages?.at(-1));
-	return first && last && first !== last ? `${first}–${last}` : first || last;
-}
-function formatPassages(passages, sourceTitle) {
-	return passages.map((passage) => {
-		const where = locationOf(passage);
-		return `<<${[sourceTitle ?? passage.source ?? "source", where].filter(Boolean).join(" · ") || "excerpt"}>>\n${passage.text}`;
-	}).join("\n\n");
-}
-//#endregion
 //#region src/host/context.js
 const EMPTY_PROFILE = Object.freeze({
+	name: "",
 	background: "",
 	goals: [],
 	strengths: [],
@@ -2056,7 +2129,7 @@ function masteryFor(course, progress, lessonId) {
 }
 async function readMaterials(store, materialIds = []) {
 	const items = [];
-	for (const id of materialIds.slice(0, 8)) try {
+	for (const id of materialIds.slice(0, 12)) try {
 		const meta = await store.readJson(store.paths.material(id), null);
 		if (!meta) continue;
 		const chunks = meta.kind === "image" ? [] : await store.readJson(store.paths.materialChunks(id), []) ?? [];
@@ -2323,6 +2396,7 @@ function join(...parts) {
 }
 function learnerBlock({ profile, mastery } = {}) {
 	const lines = [];
+	if (profile?.name) lines.push(`The learner likes to be called: ${profile.name} (use it sparingly, as a friendly tutor would)`);
 	if (profile?.background) lines.push(`Background: ${profile.background}`);
 	if (profile?.goals?.length) lines.push(`Goals: ${profile.goals.join("; ")}`);
 	if (profile?.preferences?.style) lines.push(`Prefers explanations that are: ${profile.preferences.style}`);
@@ -2414,10 +2488,11 @@ function blueprintPrompt({ goal, language, intake, materialsSummary, profile, ti
 - If materials were provided, follow their scope and order where sensible.
 - If web sources are given, use them for scope, ordering and current practice, and prefer what several of them agree on.
 - Each lesson lists 1–3 learning objectives (observable: "compute…", "explain why…") and 1–4 key concepts (short names).
+- Give each lesson a "depth": "intuition" (a feel for the idea through pictures and cases), "definition" (stating it precisely), "derivation" (deriving or proving it), "application" (using it on problems) or "extension" (edge cases, generalizations, connections). Let ideas be felt before they are formalized.
 - Add 1–3 projects (one is enough for a short course) that apply the course to something real for this learner, placed after the units they depend on. Use "kind":"code" only when the project is mainly programming or data work.
 - Pick one emoji that fits the subject.
 
-Return {"title":"…","subtitle":"one line promise of the course","emoji":"…","summary":"2–3 sentences: who it is for, what they will be able to do","level":"beginner|intermediate|advanced","units":[{"title":"…","summary":"…","objectives":["…"],"lectures":[{"title":"…","summary":"…","lessons":[{"title":"…","summary":"…","objectives":["…"],"concepts":["…"],"estMinutes":15}]}]}],"projects":[{"title":"…","kind":"code|writing|analysis|design|practice|other","brief":"…","skills":["…"],"unitIndex":<0-based unit after which it fits>,"milestones":["…"],"rubric":[{"criterion":"…","points":10}]}]}`)
+Return {"title":"…","subtitle":"one line promise of the course","emoji":"…","summary":"2–3 sentences: who it is for, what they will be able to do","level":"beginner|intermediate|advanced","units":[{"title":"…","summary":"…","objectives":["…"],"lectures":[{"title":"…","summary":"…","lessons":[{"title":"…","summary":"…","objectives":["…"],"concepts":["…"],"estMinutes":15,"depth":"intuition|definition|derivation|application|extension"}]}]}],"projects":[{"title":"…","kind":"code|writing|analysis|design|practice|other","brief":"…","skills":["…"],"unitIndex":<0-based unit after which it fits>,"milestones":["…"],"rubric":[{"criterion":"…","points":10}]}]}`)
 	};
 }
 function revisePrompt({ blueprint, instruction, language }) {
@@ -2427,10 +2502,16 @@ function revisePrompt({ blueprint, instruction, language }) {
 	};
 }
 const ITEM_FIGURE = "When a figure makes a question clearer (a shape to measure, a graph to read, a circuit, a diagram to label), give the item \"svg\": a small diagram following the same rules as the board's svg op (viewBox at most 480×320). For the graph of a formula give \"plot\" instead: an object shaped like the board's plot op, without \"params\". Most items need no figure.";
+function materialsRevisePrompt({ blueprint, materials, passages, instruction, language }) {
+	return {
+		system: join(PERSONA, `You revise course blueprints to make good use of materials the learner has added, keeping everything else intact. ${languageRule(language)}`, JSON_ONLY),
+		user: join(block("current_blueprint", blueprint), block("new_materials", materials), block("material_passages", passages), block("learner_request", instruction), `The learner added these materials to the course. Revise the blueprint so the course uses them: add lessons, or a unit, for what they cover that the course lacks, placed where the prerequisites allow; take existing lessons deeper where the materials go further; follow any request above. Keep everything else as it is, and remove a lesson only if the materials show it is wrong. Keep the "id" of every unit, lecture, lesson and concept you do not substantially change; new items get no id. Give every new lesson a "depth". Return the complete revised blueprint in the same JSON shape.`)
+	};
+}
 function reworkPrompt({ outline, unitTitle, lectureTitle, lesson, mode, language }) {
 	return {
 		system: join(PERSONA, `You design personal courses with the care of an experienced curriculum designer: clear prerequisites first, one new idea per lesson. ${languageRule(language)}`, JSON_ONLY),
-		user: join(block("course_outline", outline), block("position", `Unit: ${unitTitle}\nLecture: ${lectureTitle}`), block("lesson", lesson), mode === "split" ? "Split this lesson into two consecutive lessons that together cover everything it covers. Each teaches one coherent idea in 10–20 minutes, and the first prepares the second. Stay consistent with the rest of the course." : "Rewrite this lesson to go deeper. Keep its topic and its place in the course, but aim at why it works, its edge cases and its connections to the rest of the course; adjust the objectives, concepts and minutes (at most 25) to match.", "Return {\"lessons\":[{\"title\":\"…\",\"summary\":\"…\",\"objectives\":[\"…\"],\"concepts\":[\"…\"],\"estMinutes\":15}]}")
+		user: join(block("course_outline", outline), block("position", `Unit: ${unitTitle}\nLecture: ${lectureTitle}`), block("lesson", lesson), mode === "split" ? "Split this lesson into two consecutive lessons that together cover everything it covers. Each teaches one coherent idea in 10–20 minutes, and the first prepares the second. Stay consistent with the rest of the course." : "Rewrite this lesson to go deeper. Keep its topic and its place in the course, but aim at why it works, its edge cases and its connections to the rest of the course; adjust the objectives, concepts and minutes (at most 25) to match.", "Return {\"lessons\":[{\"title\":\"…\",\"summary\":\"…\",\"objectives\":[\"…\"],\"concepts\":[\"…\"],\"estMinutes\":15,\"depth\":\"intuition|definition|derivation|application|extension\"}]}")
 	};
 }
 function practicePrompt({ course, lecture, lessons, language, passages }) {
@@ -2460,12 +2541,19 @@ const DIRECTIVES = Object.freeze({
 	challenge: "The learner has mastered the prerequisites easily: move briskly through basics, add depth (why it works, edge cases, connections) and make the checks harder.",
 	review: "This is a REVIEW lesson: retrieve before re-explaining. Open with a question, then consolidate the key ideas with a compact board and mixed checks."
 });
+const DEPTH_GUIDANCE = Object.freeze({
+	intuition: "This lesson builds intuition: lead with pictures, analogies and concrete cases, keep the formalism light, and leave proofs for later lessons.",
+	definition: "This lesson makes the idea precise: state the definitions and notation carefully, with examples and non-examples.",
+	derivation: "This lesson derives or proves the result: work every step on the board and say why each step holds.",
+	application: "This lesson applies the idea: work through varied problems, from routine to less familiar, and show how to choose the method.",
+	extension: "This lesson goes further: edge cases, generalizations and connections to other topics."
+});
 function lessonPrompt({ course, unit, lecture, lesson, language, learner, passages, previous, directive, style }) {
 	const steps = Math.min(18, Math.max(7, Math.round((lesson.estMinutes || 15) * .7)));
 	return {
 		system: join(PERSONA, BOARD_SPEC, STEP_SPEC, languageRule(language), JSONL_ONLY),
-		user: join(block("course", `${course.title} (${course.level || "mixed level"}) — ${course.summary ?? ""}`), block("position", `Unit: ${unit.title}\nLecture: ${lecture.title}\nLesson: ${lesson.title}\nObjectives: ${lesson.objectives.join("; ")}\nConcepts (id=name): ${lesson.concepts.map((concept) => `${concept.id}=${concept.name}`).join(", ")}`), block("previous_lesson", previous), learnerBlock(learner), block("source_passages", passages), style ? block("style_request", style) : "", DIRECTIVES[directive] ?? "", `Teach this lesson in about ${steps} steps (~${lesson.estMinutes || 15} minutes).
-- Open with a hook: a question, a surprising fact, or a concrete situation the idea explains. Connect to the previous lesson when there is one.
+		user: join(block("course", `${course.title} (${course.level || "mixed level"}) — ${course.summary ?? ""}`), block("position", `Unit: ${unit.title}\nLecture: ${lecture.title}\nLesson: ${lesson.title}\nObjectives: ${lesson.objectives.join("; ")}\nConcepts (id=name): ${lesson.concepts.map((concept) => `${concept.id}=${concept.name}`).join(", ")}`), block("previous_lesson", previous), learnerBlock(learner), block("source_passages", passages), style ? block("style_request", style) : "", DIRECTIVES[directive] ?? "", DEPTH_GUIDANCE[lesson.depth] ?? "", `Teach this lesson in about ${steps} steps (~${lesson.estMinutes || 15} minutes).
+- Open with a hook: a question, a surprising fact, or a concrete situation the idea explains. Connect to the previous lesson when there is one.${learner?.profile?.name ? " Call the learner by name once, in the opening step." : ""}
 - Build intuition before formalism; then make it precise; then work at least one example fully on the board.
 - Draw a diagram, chart or plot whenever a picture makes the idea click; a plot with a slider is often the clearest way to show how a formula behaves.
 - Put 2–4 checks after the key ideas, plus one at the end; every check must name its conceptIds.
@@ -2515,6 +2603,12 @@ function correctionPrompt({ course, lesson, language, boardSoFar, item, response
 		user: join(block("course", course ? course.title : ""), block("lesson", lesson ? `${lesson.title}: ${lesson.objectives?.join("; ") ?? ""}` : ""), block("board_so_far", boardSoFar), block("problem", item.prompt), block("model_working", item.answer), block("learner_working", response), block("grader_notes", notes), "The learner just wrote out their working for this problem and went wrong somewhere. Correct it at the board in 2–3 steps, continuing on the current board: (1) write the learner's wrong line as they wrote it, in an op with an \"id\", then {\"t\":\"mark\",\"ref\":\"<that id>\",\"style\":\"box\"}, and say kindly what went wrong there and why; (2) write the corrected line and carry the working on to the right answer; (3) end with a short {\"t\":\"note\",\"tone\":\"key\",\"text\":\"…\"} holding the rule to remember. Speak to the learner directly and keep it brief. Add no check, and do not continue the lesson itself.")
 	};
 }
+function handoutPrompt({ course, lesson, language, board }) {
+	return {
+		system: join(PERSONA, `You turn a lesson into a one-page handout a learner keeps: faithful to what was taught, short, exact. ${languageRule(language)}`, JSON_ONLY),
+		user: join(block("course", course ? course.title : ""), block("lesson", `${lesson.title}: ${lesson.objectives?.join("; ") ?? ""}`), block("what_the_board_taught", board), "Write the handout from what the board taught; add nothing it did not teach. \"points\": the 3–6 key points in order, each with a \"oneLine\" a learner could repeat to a friend. \"example\": one worked example with numbers, solved step by step (one step per line). \"mistakes\": 2–4 common mistakes with the fix. \"glossary\": the terms the lesson introduced. \"questions\": 3 short questions to check oneself, with answers. Use inline math $…$ for formulas.\n\nReturn {\"title\":\"…\",\"summary\":\"2–3 sentences: what this lesson was about\",\"points\":[{\"title\":\"…\",\"oneLine\":\"…\",\"detail\":\"…\"}],\"example\":{\"problem\":\"…\",\"steps\":[\"…\"],\"answer\":\"…\"},\"mistakes\":[{\"mistake\":\"…\",\"fix\":\"…\"}],\"glossary\":[{\"term\":\"…\",\"meaning\":\"…\"}],\"questions\":[{\"question\":\"…\",\"answer\":\"…\"}]}")
+	};
+}
 function verifyStepPrompt({ course, lesson, language, board, step, stepId, note }) {
 	return {
 		system: join(PERSONA, `The learner thinks a step of your lesson is wrong. Check it the way a careful examiner would: recompute every number, re-derive every formula, and check every fact, unit, sign, label, graph and answer key. Never defend a mistake and never invent one; a different but valid method or notation is not a mistake. ${languageRule(language)}`, JSON_ONLY),
@@ -2647,4 +2741,4 @@ function getRuntime() {
 	return runtime;
 }
 //#endregion
-export { BOARD_LIMITS as $, TutorError as A, passagesFor as B, researchQueriesPrompt as C, text as Ct, summaryPrompt as D, shortPrompt as E, newId as Et, EMPTY_PROFILE as F, formatPassages as G, readProfile as H, emptyProgress as I, applyEvidence as J, passageRange as K, masteryFor as L, generateSteps as M, generateText as N, verifyItemPrompt as O, streamCounter as P, extractJson as Q, materialImages as R, reexplainPrompt as S, safeRelativePath as St, reworkPrompt as T, assertId as Tt, readProgress as U, readMaterials as V, documentParts as W, masteryPercent as X, createConceptState as Y, recommendNext as Z, profilePrompt as _, normalizeLesson as _t, blueprintPrompt as a, conceptIndex as at, questionnairePrompt as b, normalizeQuestionnaire as bt, correctionPrompt as c, flattenLessons as ct, digestPrompt as d, lessonAfter as dt, boardToPlainText as et, flashcardsPrompt as f, nextLesson as ft, practicePrompt as g, normalizeItem as gt, materialBriefPrompt as h, normalizeCheatsheet as ht, assistPrompt as i, blueprintOutline as it, generateJson as j, verifyStepPrompt as k, detectLanguage as l, insertLesson as lt, lessonPrompt as m, normalizeCards as mt, publishRuntime as n, normalizeBoard as nt, challengePrompt as o, courseProgress as ot, gradePrompt as p, normalizeBlueprint as pt, spreadPassages as q, askPrompt as r, normalizeOp as rt, cheatsheetPrompt as s, findLesson as st, getRuntime as t, estimateSpeechMs as tt, digestPartPrompt as u, intakeSummary as ut, projectReviewPrompt as v, normalizePractice as vt, revisePrompt as w, plotToText as wt, quizPrompt as x, outlineForPrompt as xt, projectsPrompt as y, normalizeProject as yt, materialsSummary as z };
+export { passageRange as $, verifyItemPrompt as A, plotToText as At, materialImages as B, quizPrompt as C, normalizeLesson as Ct, reworkPrompt as D, outlineForPrompt as Dt, revisePrompt as E, normalizeQuestionnaire as Et, generateText as F, readProgress as G, passagesFor as H, streamCounter as I, masteryPercent as J, applyEvidence as K, EMPTY_PROFILE as L, TutorError as M, newId as Mt, generateJson as N, shortPrompt as O, safeRelativePath as Ot, generateSteps as P, formatPassages as Q, emptyProgress as R, questionnairePrompt as S, normalizeItem as St, researchQueriesPrompt as T, normalizeProject as Tt, readMaterials as U, materialsSummary as V, readProfile as W, buildIndex as X, recommendNext as Y, documentParts as Z, materialsRevisePrompt as _, nextLesson as _t, blueprintPrompt as a, boardToPlainText as at, projectReviewPrompt as b, normalizeCheatsheet as bt, correctionPrompt as c, normalizeOp as ct, digestPrompt as d, courseProgress as dt, search as et, flashcardsPrompt as f, findLesson as ft, materialBriefPrompt as g, lessonAfter as gt, lessonPrompt as h, intakeSummary as ht, assistPrompt as i, BOARD_LIMITS as it, verifyStepPrompt as j, assertId as jt, summaryPrompt as k, text as kt, detectLanguage as l, blueprintOutline as lt, handoutPrompt as m, insertLesson as mt, publishRuntime as n, spreadPassages as nt, challengePrompt as o, estimateSpeechMs as ot, gradePrompt as p, flattenLessons as pt, createConceptState as q, askPrompt as r, extractJson as rt, cheatsheetPrompt as s, normalizeBoard as st, getRuntime as t, snippetOf as tt, digestPartPrompt as u, conceptIndex as ut, practicePrompt as v, normalizeBlueprint as vt, reexplainPrompt as w, normalizePractice as wt, projectsPrompt as x, normalizeHandout as xt, profilePrompt as y, normalizeCards as yt, masteryFor as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-aha-tutor",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "开窍 Aha Tutor: a personal AI tutor for DeepSeek Harness that builds a course around you and teaches it on a narrated handwriting whiteboard",
   "type": "module",
   "main": "./lib/index.js",