"""Deterministic Mind Map drawing for Memory Studio. Turns a short indented outline into an SVG in Buzan's style: a central topic, thick curved main branches that taper outward, one colour per branch, and one key word written on each line. No model or UI dependency; nothing is saved. """ from __future__ import annotations import html import math import re MAX_MAIN_BRANCHES = 8 MAX_SUB_BRANCHES = 6 MAX_LABEL_LENGTH = 40 # Colours chosen to stay readable on the map's cream background. BRANCH_COLORS = ( "#d62839", "#e07a1f", "#1f8a70", "#2f6fb0", "#7b3fb5", "#b8860b", "#c2185b", "#3d8b37", ) # Plain names for the colours above, so a recall prompt can say "the red one". BRANCH_COLOR_NAMES = ( "red", "orange", "teal", "blue", "purple", "gold", "pink", "green", ) # What a recall view hides: nothing, the details, or every branch label. HIDE_NONE = "" HIDE_DETAILS = "details" HIDE_ALL = "all" HIDDEN_LABEL = "?" BACKGROUND = "#fffdf7" CENTER_FILL = "#312e81" _MAIN_LENGTH = 190.0 _SUB_LENGTH = 125.0 _MAIN_FONT = 19 _SUB_FONT = 15 def _clean_label(line: str) -> str: text = re.sub(r"^\s*(?:\d+[.)]\s+|[-*•+]\s+)", "", line) return " ".join(text.split()) def parse_outline(text: str) -> list[tuple[str, list[str]]]: """Parse an outline: unindented lines are main branches, indented lines are sub-branches of the main branch above them. Raises ValueError with an actionable message instead of dropping anything.""" branches: list[tuple[str, list[str]]] = [] for number, raw in enumerate((text or "").splitlines(), 1): if not raw.strip(): continue expanded = raw.replace("\t", " ") indent = len(expanded) - len(expanded.lstrip(" ")) label = _clean_label(expanded) if not label: continue if len(label) > MAX_LABEL_LENGTH: raise ValueError( f"Line {number} is {len(label)} characters. Mind Map branches " f"hold a key word or two; keep each under {MAX_LABEL_LENGTH}." ) if indent == 0: branches.append((label, [])) elif not branches: raise ValueError( "The first line must be a main branch with no indentation." ) else: branches[-1][1].append(label) if not branches: raise ValueError( "Add at least one main branch: one key word per line, with " "sub-branches indented underneath." ) if len(branches) > MAX_MAIN_BRANCHES: raise ValueError( f"Use up to {MAX_MAIN_BRANCHES} main branches; this outline has " f"{len(branches)}. Group related ideas, or split it into two maps." ) crowded = [label for label, subs in branches if len(subs) > MAX_SUB_BRANCHES] if crowded: raise ValueError( f"Keep up to {MAX_SUB_BRANCHES} sub-branches per main branch. Too many " "under: " + ", ".join(crowded) + ". Add another main branch instead." ) return branches def key_word_tips(topic: str, branches: list[tuple[str, list[str]]]) -> list[str]: """Gentle reminders of Buzan's key-word rule. Never blocks drawing.""" wordy = [ label for label in [main for main, _subs in branches] + [sub for _main, subs in branches for sub in subs] if len(label.split()) > 2 ] tips = [] if wordy: tips.append( "One key word per line recalls best. Consider shortening: " + ", ".join(f"**{label}**" for label in wordy[:6]) + ("…" if len(wordy) > 6 else "") + "." ) if len(topic.split()) > 4: tips.append("Make the centre a short topic you can turn into one picture.") if all(not subs for _main, subs in branches): tips.append( "Add a few indented sub-branches under each main idea; the details " "hang off the key words." ) return tips def _text_width(text: str, font_size: int) -> float: return max(1, len(text)) * font_size * 0.58 def _tapered_curve( start: tuple[float, float], end: tuple[float, float], bend: float, width_start: float, width_end: float, steps: int = 24, ) -> str: """A filled, gently curved branch that is thicker at its start.""" (x0, y0), (x2, y2) = start, end mx, my = (x0 + x2) / 2, (y0 + y2) / 2 dx, dy = x2 - x0, y2 - y0 length = math.hypot(dx, dy) or 1.0 nx, ny = -dy / length, dx / length x1, y1 = mx + nx * bend, my + ny * bend left, right = [], [] for step in range(steps + 1): t = step / steps x = (1 - t) ** 2 * x0 + 2 * (1 - t) * t * x1 + t**2 * x2 y = (1 - t) ** 2 * y0 + 2 * (1 - t) * t * y1 + t**2 * y2 tx = 2 * (1 - t) * (x1 - x0) + 2 * t * (x2 - x1) ty = 2 * (1 - t) * (y1 - y0) + 2 * t * (y2 - y1) tl = math.hypot(tx, ty) or 1.0 px, py = -ty / tl, tx / tl half = (width_start + (width_end - width_start) * t) / 2 left.append((x + px * half, y + py * half)) right.append((x - px * half, y - py * half)) points = left + right[::-1] path = "M " + " L ".join(f"{x:.1f} {y:.1f}" for x, y in points) + " Z" return path def render_svg( topic: str, branches: list[tuple[str, list[str]]], hide: str = HIDE_NONE ) -> str: """Draw the map. The viewBox is fitted to the drawing, so it scales cleanly. ``hide`` draws a recall view: each hidden label becomes "?" on a line of the same length, so colours, positions, and shapes stay as cues while the words themselves are left out of the SVG entirely. """ elements: list[str] = [] bounds = [0.0, 0.0, 0.0, 0.0] # min_x, min_y, max_x, max_y def grow(x: float, y: float) -> None: bounds[0], bounds[1] = min(bounds[0], x), min(bounds[1], y) bounds[2], bounds[3] = max(bounds[2], x), max(bounds[3], y) def word_on_line( x: float, y: float, text: str, size: int, color: str, rightward: bool, bold: bool, hidden: bool = False, ) -> None: width = _text_width(text, size) if hidden: text = HIDDEN_LABEL x_end = x + width + 8 if rightward else x - width - 8 elements.append( f'' ) anchor = "start" if rightward else "end" text_x = x + 4 if rightward else x - 4 weight = "700" if bold else "500" elements.append( f'' f"{html.escape(text)}" ) grow(x_end, y - size - 8) grow(x_end, y + 4) count = len(branches) center_rx = max(72.0, _text_width(topic, 22) / 2 + 26) center_ry = 42.0 for index, (label, subs) in enumerate(branches): color = BRANCH_COLORS[index % len(BRANCH_COLORS)] angle = math.radians((index + 0.5) * 360 / count - 90) if count == 1: angle = 0.0 cos, sin = math.cos(angle), math.sin(angle) start = (cos * center_rx * 0.8, sin * center_ry * 0.8) end = (start[0] + cos * _MAIN_LENGTH, start[1] + sin * _MAIN_LENGTH) bend = 26 if index % 2 else -26 elements.append( f'' ) rightward = cos >= -1e-6 word_on_line( end[0], end[1], label, _MAIN_FONT, color, rightward, True, hide == HIDE_ALL, ) main_width = _text_width(label, _MAIN_FONT) + 8 hub = (end[0] + (main_width if rightward else -main_width), end[1]) spread = min(70.0, 22.0 * max(1, len(subs) - 1)) base = 0.0 if rightward else math.pi for sub_index, sub in enumerate(subs): if len(subs) == 1: offset = 0.0 else: offset = -spread / 2 + spread * sub_index / (len(subs) - 1) sub_angle = base + math.radians(offset if rightward else -offset) sub_end = ( hub[0] + math.cos(sub_angle) * _SUB_LENGTH, hub[1] + math.sin(sub_angle) * _SUB_LENGTH, ) elements.append( f'' ) word_on_line( sub_end[0], sub_end[1], sub, _SUB_FONT, color, rightward, False, hide in (HIDE_ALL, HIDE_DETAILS), ) grow(*end) elements.append( f'' ) elements.append( f'{html.escape(topic)}' ) grow(-center_rx, -center_ry) grow(center_rx, center_ry) pad = 28 min_x, min_y = bounds[0] - pad, bounds[1] - pad width, height = bounds[2] - bounds[0] + 2 * pad, bounds[3] - bounds[1] + 2 * pad title = html.escape(f"Mind Map: {topic}") return ( f'' f"{title}" f'' + "".join(elements) + "" ) def outline_markdown(topic: str, branches: list[tuple[str, list[str]]]) -> str: lines = [f"## Mind Map: {topic}", ""] for label, subs in branches: lines.append(f"- **{label}**") lines.extend(f" - {sub}" for sub in subs) return "\n".join(lines) def branch_color_name(index: int) -> str: return BRANCH_COLOR_NAMES[index % len(BRANCH_COLOR_NAMES)] def practice_cards( topic: str, branches: list[tuple[str, list[str]]] ) -> list[dict[str, str]]: """Recall cards in the map's own order: the main branches, then each branch's details. Colours are named because they are part of the map.""" count = len(branches) cards = [ { "prompt": f"**{topic}** has {count} main branch(es). Name them, " "clockwise from the top.", "answer": "\n".join( f"{index}. **{label}** ({branch_color_name(index - 1)})" for index, (label, _subs) in enumerate(branches, 1) ), } ] for index, (label, subs) in enumerate(branches): if not subs: continue cards.append( { "prompt": f"On the **{topic}** map, the {branch_color_name(index)} " f"branch **{label}** has {len(subs)} detail(s). Name them.", "answer": ", ".join(f"**{sub}**" for sub in subs), } ) return cards