fix: edit existing HTML instead of regenerating from scratch

Add edit-vs-regenerate decision logic so the agent modifies previous
HTML in place when the user requests changes, instead of always
regenerating the entire visualization from scratch.

Closes #77

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jerelvelarde

apps/agent/main.py

@@ -53,15 +53,15 @@
         - Pre-styled form elements (buttons, inputs, sliders look native automatically)
         - Pre-built SVG CSS classes for color ramps (.c-purple, .c-teal, .c-blue, etc.)
 
-        ## Visualization Workflow (MANDATORY)
+        ## New Visualization Workflow (MANDATORY for new widgets)
 
-        When producing ANY visual response (widgetRenderer, pieChart, barChart), you MUST
-        follow this exact sequence:
+        When producing a NEW visual response (widgetRenderer, pieChart, barChart), you
+        MUST follow this exact sequence:
 
         1. **Acknowledge** — Reply with 1-2 sentences of plain text acknowledging the
            request and setting context for what the visualization will show.
-        2. **Plan** — Call `plan_visualization` with your approach, technology choice,
-           and 2-4 key elements. Keep it concise.
+        2. **Plan** — Call `plan_visualization` with `mode="new"`, your approach,
+           technology choice, and 2-4 key elements. Keep it concise.
         3. **Build** — Call the appropriate visualization tool (widgetRenderer, pieChart,
            or barChart).
         4. **Narrate** — After the visualization, add 2-3 sentences walking through
@@ -70,6 +70,32 @@
         NEVER skip the plan_visualization step. NEVER call widgetRenderer, pieChart, or
         barChart without calling plan_visualization first.
 
+        If editing an existing widget, follow the Edit workflow below instead.
+
+        ## Editing Existing Visualizations
+
+        When the user asks to modify, tweak, update, or build on top of an existing
+        visualization, you should EDIT the previous HTML rather than regenerating
+        from scratch. Look at the `html` parameter from your most recent
+        widgetRenderer tool call in the conversation history — that is the current
+        widget.
+
+        **Decision rule:**
+        - If the user's request builds on, modifies, or refines the current widget
+          → EDIT mode: use the existing HTML as your starting point
+        - If the user asks for something conceptually different or unrelated
+          → NEW mode: generate fresh HTML from scratch
+
+        **Edit workflow:**
+        1. **Acknowledge** — 1 sentence confirming what you'll change.
+        2. **Plan** — Call `plan_visualization` with `mode="edit"`, a brief
+           `approach` describing only the targeted changes, and `key_elements`
+           listing just the parts being modified (not the entire widget).
+        3. **Build** — Call widgetRenderer with the FULL updated HTML. Start from
+           the previous HTML and apply only the requested changes. Do NOT strip
+           out or rewrite parts that aren't changing.
+        4. **Narrate** — 1-2 sentences describing what changed.
+
         ## Visualization Quality Standards
 
         The iframe has an import map with these ES module libraries — use `<script type="module">` and bare import specifiers:

apps/agent/skills/master-playbook/SKILL.md

@@ -44,6 +44,15 @@ User asks a question
   +- Is it emotional/personal? -> Warm text response. No visuals needed.
 ```
 
+### Editing Existing Visuals
+
+When a user asks to tweak, adjust, or build on a previous visualization:
+- Start from the previous HTML (from your last widgetRenderer call)
+- Make surgical changes — don't rewrite CSS or structure that isn't changing
+- Keep the same technology, libraries, and overall architecture
+- The edit plan should be 1-2 bullet points, not a full spec
+- Narration after an edit should be shorter (1-2 sentences)
+
 ### The 3-Layer Response Pattern
 
 Great responses layer information:

apps/agent/src/plan.py

@@ -5,17 +5,26 @@
 
 @tool
 def plan_visualization(
-    approach: str, technology: str, key_elements: list[str]
+    approach: str,
+    technology: str,
+    key_elements: list[str],
+    mode: str = "new",
 ) -> str:
     """Plan a visualization before building it. MUST be called before
     widgetRenderer, pieChart, or barChart. Outlines the approach, technology
     choice, and key elements.
 
     Args:
         approach: One sentence describing the visualization strategy.
+            For edits, describe only the targeted changes.
         technology: The primary technology (e.g. "inline SVG", "Chart.js",
             "HTML + Canvas", "Three.js", "Mermaid", "D3.js").
         key_elements: 2-4 concise bullet points describing what will be built.
+            For edits, list only the elements being modified.
+        mode: "new" for a fresh visualization, "edit" for modifying an
+            existing one.
     """
     elements = "\n".join(f"  - {e}" for e in key_elements)
+    if mode == "edit":
+        return f"Edit Plan: {approach}\nTech: {technology}\nChanges:\n{elements}"
     return f"Plan: {approach}\nTech: {technology}\n{elements}"