fix: chat virtualization stability and margin collapse fixes

- Key ChatView by sessionId to force clean virtualizer remounts on session switch
- Enable useAnimationFrameWithResizeObserver for stable row measurement during animations
- Add flow-root to virtual rows and message containers to prevent margin collapsing
- Cancel pending rAF flush on session switch to prevent stale streaming data overwrites
- Debounce space switch effect by 60ms to prevent race conditions between concurrent session operations
- Update release notes template with user-facing writing guidance

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

Author: OpenSource03

.claude/skills/release/references/release-notes-template.md

@@ -7,21 +7,45 @@
 - Use an em dash (`—`), not a hyphen
 - Name 2-3 headline features, joined by commas and `&`
 - Examples:
+  - `v0.21.0 — Virtualized Chat, Mermaid Diagrams & Deep Folder Tagging`
   - `v0.15.0 — Slash Commands, Tool Grouping & Project Files`
   - `v0.14.0 — Codex Engine Config, Auth Flow & Settings Refresh`
   - `v0.13.1 — Windows Compatibility Fixes`
 
+## Audience & Tone
+
+**Write for users, not developers.** Release notes are read by people who use the app, not people who built it.
+
+- ✅ "Long conversations are dramatically faster now"
+- ❌ "Replaced `content-visibility: auto` with `@tanstack/react-virtual` windowing"
+- ✅ "When Claude draws a diagram, it now actually renders as a visual diagram"
+- ❌ "Mermaid fenced code blocks render as SVG via async `mermaid.render()` with LRU cache"
+- ✅ "Type `/clear` in the composer and hit Enter to open a fresh chat"
+- ❌ "Added `LOCAL_CLEAR_COMMAND` slash command with `source: 'local'` that calls `onClear()` callback"
+
+**Rules of thumb:**
+- Describe what the user *experiences*, not what the code does
+- No internal names, no version numbers, no API terms, no implementation details
+- If you can't explain it in plain English, simplify or skip it
+- Bug fixes: describe the symptom the user saw, not the root cause
+
 ## Notes Structure
 
+Sections can be free-form paragraphs OR bullet lists — pick whichever reads more naturally.
+
 ```markdown
 ## What's New
 
-### {emoji} {Category Title}
-- **{Feature name}** — description of what it does
-- **{Feature name}** — description
+### {emoji} {User-Facing Section Title}
+Short paragraph explaining what changed and why users care.
+
+### {emoji} {User-Facing Section Title}
+- **{Feature name}** — what it does for the user
+- **{Feature name}** — what it does for the user
 
-### {emoji} {Category Title}
-- **{Feature name}** — description
+### 🐛 Bug Fixes
+- Fixed a bug where [symptom the user experienced]
+- Fixed [thing] that caused [user-visible problem]
 
 ---
 
@@ -31,64 +55,65 @@
 ## Rules
 
 1. Use `## What's New` for feature releases, `## Changes` for patch/fix-only releases
-2. Group under `### {emoji} {Category Title}` headers
-3. Bullets: `**bold feature name** — description` (em dash)
-4. End with `---` separator and Full Changelog link
+2. Group under `### {emoji} {Category Title}` headers — keep titles plain, not technical
+3. End with `---` separator and Full Changelog link
+4. **Always write for users first.** Internal details, library names, and implementation notes belong in commit messages and CLAUDE.md, not release notes.
 
 ## Emoji Conventions
 
 | Emoji | Category |
 |-------|----------|
-| ⚡ | Performance, speed, commands, autocomplete |
-| 📦 | Grouping, packaging, bundling |
-| 📂 | Files, filesystem, project structure |
-| 🔍 | Search, inspection, debugging |
+| ⚡ | Performance, speed, snappiness |
+| 📦 | Grouping, packaging |
+| 📂 | Files, folders, filesystem |
+| 🔍 | Search, inspection |
 | 📨 | Messages, queues, communication |
-| 🛠 | Tools, subagents, integrations |
-| 🎨 | UI, polish, visual changes, icons |
-| ⚙️ | Configuration, settings, engines |
-| 🔐 | Auth, security |
-| 🔄 | Updates, syncing, auto-refresh |
-| 🌳 | Git, worktrees, version control |
+| 🛠 | Tools, integrations |
+| 🎨 | UI, visual polish |
+| ⚙️ | Settings, configuration |
+| 🔐 | Auth, security, permissions |
+| 🔄 | Updates, syncing |
+| 🌳 | Git, version control |
 | 🐛 | Bug fixes |
 | ✨ | New features (generic) |
 
-## Example: Feature Release (v0.15.0)
+## Example: Feature Release (v0.21.0)
 
 ```markdown
 ## What's New
 
-### ⚡ Slash Command Autocomplete
-- **Unified `/` command picker** in InputBar — type `/` to browse commands from Claude, ACP, and Codex engines
-- **Keyboard navigation** with arrow keys, Enter/Tab to select, Escape to dismiss
+### ⚡ Much Faster Chat
+Long conversations are dramatically faster now. We replaced the old rendering approach with a proper virtualized list — only the messages you can actually see are rendered at any time. Scrolling is smoother, switching sessions is snappier, and the app uses less memory overall.
+
+### 📊 Mermaid Diagrams
+When Claude draws a diagram using a mermaid code block, it now actually renders as a visual diagram — flowcharts, sequence diagrams, pie charts, git graphs, and more. Diagrams adapt to your light/dark theme automatically. While Claude is still typing, you see the raw source; once the message is complete, the diagram appears.
 
-### 📦 Tool Group Collapsing
-- **Automatic grouping** — contiguous tool_call sequences merge into a collapsible summary block
-- **Animated morph transition** — tools compress into a grouped header with staggered row animations
+### 📂 Deep Folder Inclusion (`@#`)
+You can now use `@#foldername` in the composer to include the full contents of a folder — not just the file tree, but every file inside it. Regular `@folder` still gives you the structure overview. If the folder is large, Harnss will warn you before sending.
 
-### 📂 Project Files Panel
-- **Full filesystem tree browser** — walks entire project directory (skips .git, node_modules)
-- **Search filtering** with debounced input and auto-expand matching directories
+### ⌨️ `/clear` Command
+Type `/clear` in the composer and hit Enter to instantly open a fresh chat — without sending anything to the agent.
 
-### 🎨 UI & Polish
-- **App icon refresh** — display-p3 gradient, dark/light opacity specializations
-- **SDK bump** to `@anthropic-ai/claude-agent-sdk` 0.2.68
+### 🐛 Bug Fixes
+- Fixed a bug where switching out of plan mode could reset the permission level incorrectly
+- Fixed markdown characters occasionally getting eaten during streaming (apostrophes, backticks, etc.)
+- Permission prompts now show a notification if something goes wrong, instead of failing silently
 
 ---
 
-**Full Changelog**: https://github.com/OpenSource03/harnss/compare/v0.14.3...v0.15.0
+**Full Changelog**: https://github.com/OpenSource03/harnss/compare/v0.20.0...v0.21.0
 ```
 
 ## Example: Patch Release
 
 ```markdown
 ## Changes
 
-### 🐛 Windows Compatibility
-- **Windows ARM64 binary detection** — fixed Codex binary path resolution for ARM64 Windows
-- **npm pack EINVAL workaround** — handle Windows-specific EINVAL error during npm pack
+### 🐛 Bug Fixes
+- Fixed the app hanging when switching sessions during an active stream
+- Fixed copy button not working in certain sandboxed contexts
 
 ---
 
-**Full Changelog**: https://github.com/OpenSource03/harnss/compare/v0.13.0...v0.13.1
+**Full Changelog**: https://github.com/OpenSource03/harnss/compare/v0.21.0...v0.21.1
 ```

CLAUDE.md

@@ -253,9 +253,9 @@ Always search the web when needed for up-to-date API references, Electron APIs,
 **Release notes format**:
 - Start with `## What's New` (for feature releases) or `## Changes` (for smaller releases)
 - Group changes under `### Emoji Section Title` headers (e.g., `### 🌳 Git Worktree Management`)
-- Each bullet: **bold the feature name**, then describe what it does
 - End with `---` separator and `**Full Changelog**: https://github.com/OpenSource03/harnss/compare/v{prev}...v{current}`
 - Use `gh release create` with tag, then `gh release edit` to set title + notes
+- **Write for users, not developers** — describe what the user *experiences*, never mention internal names, library names, or implementation details. "Long conversations are dramatically faster" not "replaced content-visibility with @tanstack/react-virtual". Full guidance in `.claude/skills/release/references/release-notes-template.md`.
 
 **Commit message format** (conventional commits):
 - `feat: short description` — new features

package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnss",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "productName": "Harnss",
   "description": "Harness your AI coding agents — one desktop app for Claude Code, Codex, and any ACP agent",
   "author": {

src/components/ChatView.tsx

@@ -302,7 +302,10 @@ export const ChatView = memo(function ChatView(props: ChatViewProps) {
     );
   }
 
-  return <ChatViewContent {...props} />;
+  // Key by sessionId to force a clean remount on session/space switch.
+  // This guarantees a fresh Virtualizer instance with no stale itemSizeCache,
+  // measurementsCache, or ResizeObserver subscriptions from the previous session.
+  return <ChatViewContent key={props.sessionId ?? "__empty__"} {...props} />;
 });
 
 // ── ChatViewContent (inner, module-level, virtualized rendering) ──
@@ -494,6 +497,10 @@ function ChatViewContent({
     estimateSize: (index) => estimateRowHeight(rows[index]),
     getItemKey: (index) => getRowKey(rows[index]),
     overscan: 5,
+    // Row heights change via markdown margins, collapsibles, and tool-group
+    // morph animations. Measure inside rAF so ResizeObserver updates align
+    // with paint and don't race mid-transition.
+    useAnimationFrameWithResizeObserver: true,
   });
 
   // ── Scroll handling (rerender-defer-reads, rerender-use-ref-transient-values) ──
@@ -658,6 +665,7 @@ function ChatViewContent({
             key={getRowKey(rows[virtualRow.index])}
             ref={virtualizer.measureElement}
             data-index={virtualRow.index}
+            className="flow-root"
             style={{
               position: "absolute",
               top: 0,

src/components/MessageBubble.tsx

@@ -334,7 +334,7 @@ export const MessageBubble = memo(function MessageBubble({
     <div className={`flex justify-start px-4 ${isContinuation ? "py-0.5" : "py-1.5"}`}>
       <Tooltip>
         <TooltipTrigger asChild>
-          <div className="min-w-0 wrap-break-word max-w-[85%]">
+          <div className="flow-root min-w-0 max-w-[85%] wrap-break-word">
             {showThinking && message.thinking && (
               <div className={message.content ? "mb-2" : undefined}>
                 <ThinkingBlock
@@ -347,7 +347,7 @@ export const MessageBubble = memo(function MessageBubble({
             {message.content ? (
               <div
                 ref={proseRef}
-                className="prose dark:prose-invert prose-sm max-w-none text-foreground [&_li::marker]:text-foreground dark:[&_li::marker]:text-foreground/70"
+                className="flow-root prose dark:prose-invert prose-sm max-w-none text-foreground [&_li::marker]:text-foreground dark:[&_li::marker]:text-foreground/70"
               >
                 <IsStreamingMarkdownContext.Provider value={!!message.isStreaming}>
                   <ReactMarkdown

src/components/SummaryBlock.tsx

@@ -47,7 +47,7 @@ export const SummaryBlock = memo(function SummaryBlock({ message }: SummaryBlock
   const fallbackLabel = isCompact ? "Context compacted" : "Context resumed from previous conversation";
 
   return (
-    <div className="mx-4 my-2">
+    <div className="flow-root mx-4 my-2">
       <button
         type="button"
         onClick={() => hasContent && setIsOpen((prev) => !prev)}

src/components/TurnChangesSummary.tsx

@@ -136,7 +136,7 @@ export const TurnChangesSummary = memo(function TurnChangesSummary({
   }, []);
 
   return (
-    <div className="mx-4 my-2 animate-in fade-in slide-in-from-bottom-1 duration-300">
+    <div className="flow-root mx-4 my-2 animate-in fade-in slide-in-from-bottom-1 duration-300">
       {/* Collapsed header bar */}
       <button
         type="button"

src/hooks/useAppOrchestrator.ts

@@ -478,49 +478,55 @@ export function useAppOrchestrator() {
     localStorage.setItem(LAST_SESSION_KEY, JSON.stringify(map));
   }, [manager.activeSessionId, manager.isDraft, manager.sessions, projectManager.projects, readLastSessionMap]);
 
-  // When activeSpaceId changes, switch to last used session in that space
+  // When activeSpaceId changes, switch to last used session in that space.
+  // Debounced by 60ms to coalesce rapid space switches and prevent race conditions
+  // between concurrent switchSession/createSession calls.
   useEffect(() => {
     const prev = prevSpaceIdRef.current;
     const next = spaceManager.activeSpaceId;
     prevSpaceIdRef.current = next;
     if (prev === next) return;
 
-    // Find projects in the new space
-    const spaceProjectIds = new Set(
-      projectManager.projects
-        .filter((p) => (p.spaceId || "default") === next)
-        .map((p) => p.id),
-    );
+    const timer = setTimeout(() => {
+      // Find projects in the new space
+      const spaceProjectIds = new Set(
+        projectManager.projects
+          .filter((p) => (p.spaceId || "default") === next)
+          .map((p) => p.id),
+      );
 
-    // Check if current session is already in the new space
-    if (manager.activeSession && spaceProjectIds.has(manager.activeSession.projectId)) {
-      return; // Already in the right space
-    }
+      // Check if current session is already in the new space
+      if (manager.activeSession && spaceProjectIds.has(manager.activeSession.projectId)) {
+        return; // Already in the right space
+      }
 
-    // Try to restore the last used session in this space
-    const map = readLastSessionMap();
-    const lastSessionId = map[next];
-    if (lastSessionId) {
-      const session = manager.sessions.find(
-        (s) => s.id === lastSessionId && spaceProjectIds.has(s.projectId),
+      // Try to restore the last used session in this space
+      const map = readLastSessionMap();
+      const lastSessionId = map[next];
+      if (lastSessionId) {
+        const session = manager.sessions.find(
+          (s) => s.id === lastSessionId && spaceProjectIds.has(s.projectId),
+        );
+        if (session) {
+          manager.switchSession(session.id);
+          return;
+        }
+      }
+
+      // No remembered chat for this space: open a fresh draft chat in the space.
+      // If the space has no projects, we can't create a draft chat yet.
+      const firstProjectInSpace = projectManager.projects.find(
+        (p) => (p.spaceId || "default") === next,
       );
-      if (session) {
-        manager.switchSession(session.id);
-        return;
+      if (firstProjectInSpace) {
+        void handleNewChat(firstProjectInSpace.id);
+      } else {
+        // No projects in this space — deselect
+        manager.deselectSession();
       }
-    }
+    }, 60);
 
-    // No remembered chat for this space: open a fresh draft chat in the space.
-    // If the space has no projects, we can't create a draft chat yet.
-    const firstProjectInSpace = projectManager.projects.find(
-      (p) => (p.spaceId || "default") === next,
-    );
-    if (firstProjectInSpace) {
-      void handleNewChat(firstProjectInSpace.id);
-    } else {
-      // No projects in this space — deselect
-      manager.deselectSession();
-    }
+    return () => clearTimeout(timer);
   }, [spaceManager.activeSpaceId]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // Sync model from loaded session (canonical runtime names -> picker values)

src/hooks/useEngineBase.ts

@@ -73,6 +73,11 @@ export function useEngineBase({
 
   // Reset state when sessionId changes, restoring background state if available
   useEffect(() => {
+    // Cancel any pending rAF flush from the previous session to prevent stale
+    // streaming data from overwriting the new session's messages.
+    cancelAnimationFrame(rafId.current);
+    pendingFlush.current = false;
+
     setMessages(initialMessages ?? []);
     if (initialMeta) {
       setIsProcessing(initialMeta.isProcessing);