deeptutor-visualize 1.7.0__py3-none-any.whl

deeptutor/agents/visualize/prompts/zh/code_generator_agent.yaml

@@ -0,0 +1,161 @@
+system_base: |
+  你是 DeepTutor 的可视化代码生成器。根据分析简报、用户请求和对话历史，
+  为一个可视化输出可渲染的代码。
+
+  输出契约：
+  - 只输出代码，用一个带正确语言标签的代码块包裹（```svg、```javascript、
+    ```mermaid 或 ```html）。不要解释、不要前言、不要第二个代码块。
+  - 代码必须完整且自包含——它会被直接渲染，前后不会再拼接任何内容。
+
+rules_general: |
+  以下规则适用于所有渲染类型。
+
+  复杂度预算（硬性上限——稀疏而正确的图胜过密集的图）：
+  - 图中副标题最多 5 个词。细节放在对话正文里，不要塞进图里。
+  - 最多用 2-3 种颜色。颜色用来编码含义（类别 / 状态），绝不用于装饰。
+    同类元素共用一种颜色；通用 / 结构 / 起止节点用中性灰。
+  - 一行最多放 4 个全宽方框。5 个以上 → 缩小或换到第二行。
+  - 如果请求列出 6 个以上组件，不要硬塞进一张图。先画只含主流程的精简总览，
+    并在对话正文里说明用户可以针对任意子流程要求展开细节。
+
+  文本：
+  - 全部用句首大写（标签、标题、说明）。不要每词首字母大写，不要全大写。
+  - 每个标签都要可读：对比度足够，字号不小于 11px。
+
+rules_svg: |
+  渲染类型：SVG。图会内联到页面中（不再是 <img>），因此继承 app 的主题和字体，
+  也可以交互。用下面的预置 class 来配色和排版，而不是写死 fill——这才能让图自动
+  跟随明暗模式。
+
+  - 根元素：`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 W H">`。必须设
+    xmlns 和驼峰 viewBox（写 `viewBox`，不能写 `viewbox`）；用 viewBox 控制尺寸，
+    不要写死 width/height。
+  - 只输出一个 `<svg>`。如果图有多个部分，把它们作为同一个 svg 内部的区域来排版
+    （上下堆叠、左右分栏、带标签的分区）——绝不输出多个 `<svg>`；分开的 svg 会渲染成
+    彼此割裂的碎片。内部引用用 `href` 而非 `xlink:href`（若必须用 xlink，在根上声明
+    `xmlns:xlink`）。
+  - 格式良好的 XML：每个标签闭合、每个属性带引号、`&` 写成 `&amp;`。输出按严格
+    XML 解析——一个未转义字符就会让整张图渲染失败。
+  - 不要画背景 `<rect>`，不要在 text 上写死 fill / 字体。背景由宿主提供；下面的
+    class 提供随明暗自适应的颜色。背景保持透明。
+
+  预置 class（由宿主统一定义——用它们，绝不内联颜色）：
+  - 文本：`class="t"`（14px）、`class="th"`（14px 中粗，用于标题）、`class="ts"`
+    （12px，用于副标题 / 说明）。只用两种字号。每个 `<text>` 都带一个。
+  - 中性：`class="box"`（容器框）、`class="arr"`（箭头线——加
+    `marker-end="url(#arrow)"`）、`class="leader"`（虚线引导线）。
+  - 颜色色板，加在 `<g>` 或形状上，从中选一个：`c-gray c-blue c-teal c-coral
+    c-pink c-purple c-green c-amber c-red`。它同时设置形状的 fill+stroke 和内部
+    `<text>` 的颜色，明暗模式都适配。最多用 2-3 个色板；灰色用于中性 / 结构 / 起止。
+    通用类别优先用 purple/teal/coral；blue/green/amber/red 留给
+    信息/成功/警告/错误语义。
+  - 用法：把 `c-*` 色板加在包住形状和 `<text>` 的 `<g>` 上，文字会自动取到对应的
+    可读颜色。
+
+  箭头 marker——包含一次，用 `marker-end="url(#arrow)"` 引用：
+  `<defs><marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.5"/></marker></defs>`
+
+  交互（可选）：想让某个节点点击后深入讲解，在它的 `<g>` 上加
+  `data-prompt="<一个简短的追问>"`——点击会把这个问题发送到对话。用于学习者自然
+  会想展开的节点。
+
+  坐标计算——SVG 大多数失败源于算术，所以先算后画：
+  - 框宽由最长标签决定：`width = max(标题字数*8, 副标题字数*7) + 24`。
+    100px 的框约容纳 10 个副标题字符。特殊字符（公式、∑、₆、下标）更宽，加 30-50%。
+  - 行内排布：放一行 N 个框前，先核算总宽是否落在安全区（x=40..640）。例如四个
+    130px 框 + 三个 20px 间隙 = 580 ≤ 600。放不下就缩小或换行——绝不让框重叠。
+  - 箭头走线：画 A→B 的线之前，确认它不穿过任何其他框的内部或任何标签。会穿过
+    就用 L 形折线绕开。
+  - SVG 的 `<text>` 不会自动换行。需要两行就用显式 `<tspan x=... dy="1.2em">`。
+    如果长到需要换行，说明它太长了——精简它。
+  - 宿主会把每个 `<text>` 在其 `y` 上垂直居中（dominant-baseline: central——
+    你自己不要设置它）。让标签在框内居中：x = 框中心并配 `text-anchor="middle"`，
+    y = 框中心。标题 + 副标题成对时，y 分别取中心−9 和中心+9。
+
+  viewBox 终检清单——定稿前逐条核对：
+  1. viewBox 高度 = （最底部元素的 y + 高度）+ 40px 余量。
+  2. 所有内容落在 x=0..W、y=0..H 内；绝不使用负坐标。
+  3. 无关的框、标签、箭头之间没有意外重叠。
+  4. `text-anchor="end"` 会从 x 向左延伸——x 较小时可能越过 x=0；优先用
+     `text-anchor="start"` 并把整列右对齐。
+
+  按 `visual_genre` 指示的教学意图匹配画法：
+  - flowchart：顺序步骤 / 决策分支。框 + 箭头，单一方向（全部自上而下或全部从左
+    到右），≤5 个节点。循环用一条返回箭头加 "↻ 回到起点" 的注记表示——不要把框
+    排成环（环形布局会碰撞；若循环有逐阶段细节，分析阶段本应选 html stepper）。
+  - structural：包含关系。大的圆角容器框（浅填充），内部更小的区域框（更深一档或
+    相关色），嵌套 ≤2-3 层，每个容器内留 20px 内边距。
+  - illustrative：用空间隐喻建立直觉——画机制本身，而不是关于机制的图。颜色编码
+    强度（暖 = 活跃 / 热，冷 = 平静 / 冷，灰 = 惰性）。形状可重叠以表现层次；文字
+    绝不与笔画交叠——把标签放在安静的边缘，用细引导线指向。
+  - 其它 genre：参照以上三种里最接近的画法。
+
+rules_chartjs: |
+  渲染类型：Chart.js。输出严格 JSON 对象（不是 JavaScript 对象字面量），作为配置
+  传给 `new Chart(ctx, config)`：
+  - 键和字符串值都用双引号。不要函数回调、不要注释、不要尾逗号、不要 `undefined`。
+    必须能被 `JSON.parse` 解析。
+  - 必须包含 `"type"` 和 `"data"`；坐标轴 / 图例配置放在 `"options"`。按数据选择
+    合适的图表类型（bar / line / pie / doughnut / radar / scatter / bubble /
+    polarArea）。
+  - 用可读的现代配色。绝不只靠颜色区分系列——分类数据要把数值 / 标签放进数据里，
+    让图例有意义。
+  - 数据里预先算好的数字要四舍五入，不要带出浮点误差。
+
+rules_mermaid: |
+  渲染类型：Mermaid.js。输出有效的 Mermaid DSL：
+  - 第一行非空内容是有效的图表类型关键词：graph / flowchart / sequenceDiagram /
+    classDiagram / stateDiagram-v2 / erDiagram / gantt / mindmap / pie /
+    journey / timeline。
+  - 节点 ID 不含空格——用 camelCase 或下划线。显示文字放在方括号里：
+    `nodeId[显示标签]`。绝不用保留字（end、graph、subgraph、class）作为裸节点 ID。
+  - 数据库模式 / ERD 用 `erDiagram`；类结构用 `classDiagram`。这些布局问题
+    Mermaid 会自动解决——不要在 SVG 里手画。
+  - 标签简短可读；核对图表类型关键词与你描述的结构一致。
+
+rules_mindmap: |
+  渲染类型：Mermaid 思维导图。只输出有效的 Mermaid `mindmap` DSL：
+  - 第一个非空行必须是 `mindmap`。
+  - 只有一个根节点，层级缩进保持一致；至少包含一个子分支，不能出现多个根。
+  - 优先使用简短名词标签，层级不超过三层。不要输出 Markdown 围栏、流程图箭头
+    或其他 Mermaid 图表语法。
+
+rules_html: |
+  渲染类型：HTML。输出一个完整、自包含的单文件 HTML 页面，用于交互式讲解、分步
+  走读、UI 原型或可点击演示。
+  - 从 `<!DOCTYPE html>` 写到 `</html>`。所有 CSS 放在 `<style>`；所有 JavaScript
+    放在 `</body>` 前的 `<script>` 里。
+  - 页面在沙箱 iframe（null origin）中渲染。只能从这些 CDN 加载库——
+    cdn.jsdelivr.net、cdnjs.cloudflare.com、unpkg.com，其它一律被拦截。KaTeX 由
+    宿主自动注入（`$...$` / `$$...$$`）。推荐：Chart.js 做图表，d3 + topojson 做
+    数据可视化 / 地图。
+  - 地理地图：拉取真实拓扑数据，绝不手编坐标。美国各州：
+    `cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json`（d3.geoAlbersUsa）。
+    世界：`cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json`
+    （d3.geoNaturalEarth1）。用文件里真实的 feature 名 / id 来对应数据。
+  - 宿主会按内容高度自动调整 iframe 高度——不要设固定的 body 高度；用
+    `max-width: 100%` 和 `box-sizing: border-box`。
+  - 追问：调用 `sendPrompt("一个简短的问题")`（例如从按钮的 onclick）把这个问题
+    投到对话输入框。用在学习者自然会想深入的地方。
+  - 对循环或分阶段流程，构建 stepper：每个阶段一个面板，用圆点 / 药丸显示位置，
+    Next 按钮从最后一个阶段绕回第一个。每个面板自带内容，互不碰撞。
+  - 在以上约束内自由决定布局、配色和交互，让页面清晰、美观、易学。
+
+user_template: |
+  用户请求：
+  {user_input}
+
+  对话历史：
+  {history_context}
+
+  渲染类型：{render_type}
+
+  分析简报（注意 `visual_genre`——它告诉你要生成哪种风格的 {render_type}）：
+  {analysis_json}
+
+  现在生成可视化代码，作为一个代码块：
+  - SVG 用：```svg ... ```
+  - Chart.js 用：```javascript ... ```
+  - Mermaid 用：```mermaid ... ```
+  - 思维导图用：```mermaid ... ```
+  - HTML 用：```html ... ```

deeptutor/agents/visualize/prompts/zh/review_agent.yaml

@@ -0,0 +1,35 @@
+repair_system: |
+  你是一个可视化代码修复器。生成的代码未通过确定性的本地校验，并附上了确切的错误。
+  用最小的改动修复"那个具体缺陷"，使代码有效且可渲染——不要重新设计、重新配色，
+  也不要重新评判其余部分。
+
+  - svg：返回一个格式良好的 `<svg>`，含 xmlns 和驼峰 `viewBox`。如果有多个 `<svg>`，
+    合并成一个（各部分作为内部区域）。用预置 class（t/ts/th、box、arr、c-*）来配色和
+    排版文本，不要写死 fill。
+  - chartjs：返回严格 JSON（键用双引号；无函数、注释或尾逗号），包含 "type" 和 "data"。
+  - mermaid：以有效的图表类型关键词开头；节点 ID 不含空格。
+  - 保留原有意图和内容。只改必要的部分。
+
+  返回一个 JSON 对象，不要包含 JSON 以外的任何文本。
+
+repair_user_template: |
+  用户请求：
+  {user_input}
+
+  渲染类型：{render_type}
+
+  必须修复的校验错误：
+  {error}
+
+  分析简报：
+  {analysis_json}
+
+  未通过校验的代码：
+  {code}
+
+  返回 JSON：
+  {{
+    "optimized_code": "修正后、可渲染的代码",
+    "changed": true 或 false,
+    "review_notes": "修复了什么"
+  }}

deeptutor/agents/visualize/prompts/zh/visualize.yaml

@@ -0,0 +1,14 @@
+# Visualize capability status messages (Chinese)
+# Loaded by StatusI18n from the `status:` section.
+status:
+  analyzing: "正在分析可视化需求..."
+  generating: "正在生成可视化代码..."
+  manim_code_prepared: "Manim 代码已准备好。"
+  manim_rendering: "正在渲染 {mode}，质量={quality}。"
+  manim_retry: "重试 {attempt}：{error}"
+  manim_artifacts_one: "已准备 {count} 个产物。"
+  manim_artifacts_many: "已准备 {count} 个产物。"
+  llm_call_failed: "LLM 调用失败。"
+  tool_calling_disabled: "{target} 未启用工具调用，而可视化只能通过 submit_visualization 工具调用提交到画布。请在 设置 → 模型 → LLM → 能力 → 工具调用 中选择「已支持」。"
+  no_payload: "可视化智能体结束时没有产出有效的画布内容。推理模型可能在思考阶段就耗尽了大部分输出预算，导致 submit_visualization 调用还没写完就被截断。如果反复出现，请在 设置 → 能力 → 可视化 中调高「最大 token 数」。"
+  no_payload_tool_calling_disabled: "本次没有提交任何可视化：{target} 未启用工具调用，模型无法调用 submit_visualization，而这是把内容交给画布的唯一途径。本地服务（LM Studio、Ollama、vLLM、llama.cpp）默认关闭工具调用；请在 设置 → 模型 → LLM → 能力 → 工具调用 中把该模型声明为「已支持」，然后重新生成。"

deeptutor/agents/visualize/utils.py

@@ -0,0 +1,210 @@
+"""Utility helpers for the visualize pipeline."""
+
+from __future__ import annotations
+
+import json
+import re
+
+import defusedxml.ElementTree as ET
+
+from deeptutor.agents._shared.json_output import extract_json_object
+
+_MERMAID_KEYWORDS = (
+    "graph",
+    "flowchart",
+    "sequenceDiagram",
+    "classDiagram",
+    "stateDiagram-v2",
+    "stateDiagram",
+    "erDiagram",
+    "gantt",
+    "mindmap",
+    "pie",
+    "journey",
+    "gitGraph",
+    "timeline",
+    "quadrantChart",
+    "requirementDiagram",
+    "sankey-beta",
+    "xychart-beta",
+    "block-beta",
+    "C4Context",
+)
+
+
+def extract_code_block(text: str, language: str = "") -> str:
+    """Extract a fenced code block from LLM output.
+
+    If *language* is given the block must start with that tag;
+    otherwise any triple-backtick fence is accepted.
+    """
+    # Closing fence may sit on the same line as the last content line.
+    if language:
+        pattern = rf"```{re.escape(language)}\s*\n([\s\S]*?)\n?```"
+    else:
+        pattern = r"```[A-Za-z]*\s*\n([\s\S]*?)\n?```"
+    match = re.search(pattern, text or "", re.IGNORECASE)
+    if match:
+        return match.group(1).strip()
+    return (text or "").strip()
+
+
+def is_valid_html_document(html: str) -> bool:
+    """Heuristic check that *html* looks like a renderable HTML fragment."""
+    if not html:
+        return False
+    lowered = html.lower()
+    return "<html" in lowered or "<!doctype" in lowered or "<body" in lowered or "<div" in lowered
+
+
+def build_fallback_html(*, title: str, summary: str = "", note: str = "") -> str:
+    """Build a minimal, self-contained fallback HTML page.
+
+    Used when the model fails to produce a renderable HTML document, so the
+    user still gets *something* shown in the iframe instead of a blank panel.
+    """
+    safe_title = (title or "Visualization").strip() or "Visualization"
+    safe_summary = (summary or "").replace("\n", "<br>") or (
+        "The model did not return a renderable HTML document."
+    )
+    safe_note = (note or "").replace("\n", "<br>")
+
+    note_block = (
+        f'<div class="note"><strong>Note:</strong><br>{safe_note}</div>' if safe_note else ""
+    )
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>{safe_title}</title>
+<style>
+  *{{margin:0;padding:0;box-sizing:border-box;}}
+  body{{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;
+       background:linear-gradient(135deg,#F8FAFC 0%,#EFF6FF 100%);
+       min-height:100vh;padding:2rem;color:#1E293B;}}
+  .card{{max-width:760px;margin:0 auto;background:#fff;border-radius:16px;
+        padding:1.75rem 2rem;box-shadow:0 4px 6px -1px rgba(0,0,0,.08);}}
+  h1{{color:#1E40AF;font-size:1.4rem;margin-bottom:1rem;}}
+  .summary{{line-height:1.7;color:#475569;}}
+  .note{{margin-top:1rem;padding:0.9rem 1rem;background:#FEF3C7;
+        border-left:4px solid #F59E0B;border-radius:0 8px 8px 0;color:#92400E;}}
+</style>
+</head>
+<body>
+  <div class="card">
+    <h1>{safe_title}</h1>
+    <div class="summary">{safe_summary}</div>
+    {note_block}
+  </div>
+</body>
+</html>"""
+
+
+def _strip_outer_fence(text: str) -> str:
+    """Drop a single wrapping triple-backtick fence, if present."""
+    stripped = (text or "").strip()
+    match = re.match(r"^```[A-Za-z]*\s*\n?([\s\S]*?)\n?```$", stripped)
+    return match.group(1).strip() if match else stripped
+
+
+def validate_visualization(code: str, render_type: str) -> tuple[bool, str]:
+    """Cheap, deterministic, local render-ability check.
+
+    Returns ``(ok, error)``. When ``ok`` is False, ``error`` is a short,
+    LLM-actionable message used to drive a single repair pass — none of these
+    failures need an LLM call to *discover*. This replaces the generic LLM
+    review for the text render types: only when local validation fails do we
+    spend a model call (a targeted repair, not an open-ended review).
+    """
+    text = (code or "").strip()
+    if not text:
+        return False, "Generated code is empty."
+
+    if render_type == "svg":
+        if "<svg" not in text.lower():
+            return False, "SVG must contain a root <svg> element."
+        try:
+            root = ET.fromstring(text)
+        except ET.ParseError as exc:
+            return False, f"SVG is not well-formed XML: {exc}"
+        tag = root.tag.split("}")[-1].lower()
+        if tag != "svg":
+            return False, f"Root element must be <svg>, found <{tag}>."
+        # Case-sensitive: SVG only honors the camelCase ``viewBox``; a
+        # lowercase ``viewbox`` is ignored by the browser and collapses the
+        # figure, so it must NOT pass validation.
+        if "viewBox" not in root.attrib:
+            return False, (
+                "SVG root is missing a viewBox attribute (must be camelCase "
+                "`viewBox`, required for responsive scaling)."
+            )
+        return True, ""
+
+    if render_type == "chartjs":
+        candidate = _strip_outer_fence(text)
+        try:
+            config = json.loads(candidate)
+        except (json.JSONDecodeError, TypeError):
+            return False, (
+                "Chart.js config must be strict JSON: double-quoted keys, no "
+                "function callbacks, no comments, no trailing commas."
+            )
+        if not isinstance(config, dict):
+            return False, "Chart.js config must be a JSON object."
+        missing = [field for field in ("type", "data") if field not in config]
+        if missing:
+            return False, f"Chart.js config is missing required field(s): {', '.join(missing)}."
+        return True, ""
+
+    if render_type == "mermaid":
+        first_line = next((ln.strip() for ln in text.splitlines() if ln.strip()), "")
+        # `---` front-matter and `%%{init}` directives are valid lead-ins.
+        if (
+            first_line.startswith(_MERMAID_KEYWORDS)
+            or first_line.startswith("%%")
+            or first_line.startswith("---")
+        ):
+            return True, ""
+        return False, (
+            "Mermaid code must start with a valid diagram keyword (graph, "
+            "flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, "
+            "erDiagram, gantt, mindmap, ...)."
+        )
+
+    if render_type == "mindmap":
+        if text.startswith("```"):
+            return False, "Mermaid mindmap output must be raw DSL without a Markdown fence."
+        lines = [
+            (line, len(line) - len(line.lstrip()))
+            for line in text.splitlines()
+            if line.strip() and not line.lstrip().startswith("%%")
+        ]
+        if not lines or lines[0][0].strip() != "mindmap":
+            return False, "Mermaid mindmap output must start with the `mindmap` keyword."
+        if len(lines) < 2:
+            return False, "Mermaid mindmap output must contain exactly one non-empty root node."
+        root_indent = lines[1][1]
+        if any(indent <= root_indent for _, indent in lines[2:]):
+            return False, "Mermaid mindmap output must contain exactly one non-empty root node."
+        if not any(indent > root_indent for _, indent in lines[2:]):
+            return False, "Mermaid mindmap output needs at least one child branch."
+        return True, ""
+
+    if render_type == "html":
+        if is_valid_html_document(text):
+            return True, ""
+        return False, "Output does not look like a renderable HTML document."
+
+    # Unknown render types are not gated.
+    return True, ""
+
+
+__all__ = [
+    "build_fallback_html",
+    "extract_code_block",
+    "extract_json_object",
+    "is_valid_html_document",
+    "validate_visualization",
+]

deeptutor/api/routers/visualizers.py

@@ -0,0 +1,144 @@
+"""Per-user visualizer catalog, lifecycle and sandbox asset routes."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import tempfile
+
+from fastapi import APIRouter, File, HTTPException, UploadFile
+from fastapi.responses import FileResponse
+
+from deeptutor.visualizers.registry import get_visualizer_registry
+from deeptutor.visualizers.store import VisualizerStoreError
+
+router = APIRouter()
+
+_MAX_UPLOAD_BYTES = 25 * 1024 * 1024
+_IFRAME_CSP = (
+    "default-src 'self'; "
+    "script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval'; "
+    "style-src 'self' 'unsafe-inline'; "
+    "img-src 'self' data: blob:; "
+    "font-src 'self' data:; "
+    "media-src 'self' data: blob:; "
+    "connect-src 'none'; frame-src 'none'; object-src 'none'; "
+    "base-uri 'none'; form-action 'none'; frame-ancestors 'self'"
+)
+
+
+def _http_error(exc: VisualizerStoreError) -> HTTPException:
+    detail = str(exc)
+    if "not found" in detail:
+        return HTTPException(status_code=404, detail=detail)
+    if "already installed" in detail or "reserved" in detail:
+        return HTTPException(status_code=409, detail=detail)
+    return HTTPException(status_code=400, detail=detail)
+
+
+@router.get("/list")
+async def list_visualizers() -> dict[str, object]:
+    registry = get_visualizer_registry()
+    return {
+        "schema_version": "deeptutor.visualizer-catalog/v1",
+        "visualizers": registry.public_catalog(),
+    }
+
+
+@router.post("/bundled/{visualizer_id}/install")
+async def install_bundled(visualizer_id: str) -> dict[str, object]:
+    registry = get_visualizer_registry()
+    try:
+        registry.install_bundled(visualizer_id)
+    except VisualizerStoreError as exc:
+        raise _http_error(exc) from exc
+    plugin = registry.get(visualizer_id)
+    return {"status": "installed", "visualizer": plugin.manifest.id if plugin else visualizer_id}
+
+
+@router.post("/{visualizer_id}/enable")
+async def enable_visualizer(visualizer_id: str) -> dict[str, str]:
+    registry = get_visualizer_registry()
+    try:
+        registry.set_enabled(visualizer_id, True)
+    except VisualizerStoreError as exc:
+        raise _http_error(exc) from exc
+    return {"status": "enabled", "visualizer": visualizer_id}
+
+
+@router.post("/{visualizer_id}/disable")
+async def disable_visualizer(visualizer_id: str) -> dict[str, str]:
+    registry = get_visualizer_registry()
+    try:
+        registry.set_enabled(visualizer_id, False)
+    except VisualizerStoreError as exc:
+        raise _http_error(exc) from exc
+    return {"status": "disabled", "visualizer": visualizer_id}
+
+
+@router.delete("/{visualizer_id}")
+async def uninstall_visualizer(visualizer_id: str) -> dict[str, str]:
+    registry = get_visualizer_registry()
+    try:
+        registry.uninstall(visualizer_id)
+    except VisualizerStoreError as exc:
+        raise _http_error(exc) from exc
+    return {"status": "uninstalled", "visualizer": visualizer_id}
+
+
+@router.post("/import")
+async def import_visualizer(
+    file: UploadFile = File(...),  # noqa: B008
+) -> dict[str, object]:
+    """Install one declarative ``visualizer.json`` + iframe bundle zip."""
+
+    if not str(file.filename or "").lower().endswith(".zip"):
+        raise HTTPException(status_code=400, detail="visualizer package must be a zip file")
+
+    fd, temp_name = tempfile.mkstemp(prefix="deeptutor-visualizer-", suffix=".zip")
+    os.close(fd)
+    temp_path = Path(temp_name)
+    total = 0
+    try:
+        with temp_path.open("wb") as sink:
+            while chunk := await file.read(1 << 20):
+                total += len(chunk)
+                if total > _MAX_UPLOAD_BYTES:
+                    raise HTTPException(
+                        status_code=413,
+                        detail="visualizer package exceeds 25 MB",
+                    )
+                sink.write(chunk)
+        registry = get_visualizer_registry()
+        try:
+            plugin = registry.install_archive(temp_path)
+        except VisualizerStoreError as exc:
+            raise _http_error(exc) from exc
+        catalog = registry.public_catalog()
+        public_manifest = next(item for item in catalog if item["id"] == plugin.manifest.id)
+        return {
+            "status": "installed",
+            "visualizer": plugin.manifest.id,
+            "manifest": public_manifest,
+        }
+    finally:
+        temp_path.unlink(missing_ok=True)
+        await file.close()
+
+
+@router.get("/{visualizer_id}/assets/{asset_path:path}")
+async def get_visualizer_asset(visualizer_id: str, asset_path: str) -> FileResponse:
+    registry = get_visualizer_registry()
+    try:
+        path = registry.asset_path(visualizer_id, asset_path)
+    except VisualizerStoreError as exc:
+        raise _http_error(exc) from exc
+    return FileResponse(
+        path,
+        headers={
+            "Cache-Control": "private, max-age=300",
+            "Content-Security-Policy": _IFRAME_CSP,
+            "Cross-Origin-Resource-Policy": "same-origin",
+            "X-Content-Type-Options": "nosniff",
+        },
+    )

deeptutor/visualizers/README.md

@@ -0,0 +1,79 @@
+# DeepTutor visualizer package protocol
+
+A visualizer type is a declarative agent contract plus a canvas renderer. User
+packages are zip archives with this shape:
+
+```text
+fraction_tiles.zip
+├── visualizer.json
+├── index.html
+├── renderer.js
+└── renderer.css
+```
+
+`visualizer.json` describes when the agent should choose the type, the payload
+it must generate, and the iframe entry point:
+
+```json
+{
+  "id": "fraction_tiles",
+  "version": "1.0.0",
+  "display_name": "Fraction Tiles",
+  "description": "Interactive comparison of fractions.",
+  "subjects": ["mathematics"],
+  "intents": ["compare", "explore"],
+  "render_target": "iframe",
+  "renderer_entry": "index.html",
+  "payload_format": "application/json",
+  "payload_kind": "json",
+  "payload_schema": {
+    "type": "object",
+    "required": ["fractions"],
+    "properties": {
+      "fractions": {
+        "type": "array",
+        "items": {"type": "string"},
+        "minItems": 1
+      }
+    },
+    "additionalProperties": false
+  },
+  "prompt": "Return equivalent fractions that directly answer the learner's request."
+}
+```
+
+Imported packages are intentionally declarative: they cannot ship Python or
+register backend code. Their renderer runs in a script-only sandbox with no
+network access. Local JSON Schema is validated before a payload reaches the
+canvas; remote schema references are rejected.
+
+When the iframe loads, the host sends:
+
+```js
+{
+  type: "deeptutor:visualization:render",
+  schema_version: "deeptutor.visualization/v1",
+  renderer,
+  payload,
+  presentation,
+  interaction
+}
+```
+
+The renderer may send two messages back to its parent:
+
+```js
+parent.postMessage({
+  type: "deeptutor:visualization:resize",
+  height: document.documentElement.scrollHeight
+}, "*");
+
+parent.postMessage({
+  type: "deeptutor:visualization:prompt",
+  text: "Why are these fractions equivalent?"
+}, "*");
+```
+
+Core native renderers and bundled optional types use the same versioned canvas
+envelope. Their trusted validators and native React components live in the
+host, while installation state remains per user.

deeptutor/visualizers/__init__.py

@@ -0,0 +1,20 @@
+"""Pluggable visualization types used by chat and the visualize capability."""
+
+from .protocol import (
+    VISUALIZATION_RESULT_KEY,
+    VISUALIZE_MODE_KEY,
+    VisualizationEnvelope,
+    VisualizerManifest,
+    VisualizerPlugin,
+)
+from .registry import VisualizerRegistry, get_visualizer_registry
+
+__all__ = [
+    "VISUALIZATION_RESULT_KEY",
+    "VISUALIZE_MODE_KEY",
+    "VisualizationEnvelope",
+    "VisualizerManifest",
+    "VisualizerPlugin",
+    "VisualizerRegistry",
+    "get_visualizer_registry",
+]