@alexleekt/pi-ask-user-glimpse 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,73 @@
 
 All notable changes to `@alexleekt/pi-ask-user-glimpse` are documented in this file.
 
+## [Unreleased]
+
+### Added
+- **Agent preamble capture** — When the agent writes an introductory message before calling `ask_user`, that text is now automatically captured and prepended to the context panel. The extension finds the most recent assistant journal entry, extracts its text content, and appends it to the dialog's left panel (separated by a horizontal rule from any explicit `context` provided by the agent). This ensures the user sees the full reasoning that led to the question, not just the question itself.
+
+### Fixed
+- **Markdown in question header** — The `question` field is now rendered through `marked` so inline markdown (bold `**`, italic `*`, code `` ` ``, links) displays correctly instead of showing raw escape characters. The HTML is sanitized with the same defense-in-depth sanitizer used by the context panel. Extracted shared `sanitizeHtml()`, `renderMarkdown()`, and `renderMarkdownInline()` to `webview/src/util/markdown.ts`.
+
+## [0.4.1] — 2026-05-20
+
+### Security
+- **Comprehensive HTML sanitization** — `ContextPanel.sanitizeHtml()` now blocks `img`, `iframe`, `object`, `embed`, `form`, `input`, `style`, `link`, `svg`, `math`, `meta`, `base`, `noscript`, `template`, `portal`, `frame`, `frameset` tags, plus `javascript:` and `data:` URLs in `href`/`src`/`action` attributes.
+- **XSS-safe search highlighting** — `highlightMatch()` in new `webview/src/util/html.ts` escapes both display text and query strings before wrapping matches in `<mark>`. Replaces raw `.replace()` in `SingleSelect` and `MultiSelect` that was vulnerable to search query injection.
+
+### Changed
+- **Prominent question header** — Removed sparkle icon and "Ask User" branding. The header now shows the full non-truncated question text in `text-base` font, wrapping naturally.
+- **50/50 panel split** — Default context/options panel width changed from 40/60 to 50/50.
+- **Invisible splitter track** — Removed grey divider bar. Only a centered grip handle is visible (`w-1` by default, `w-1.5` on drag). Handle sits exactly at the panel boundary.
+- **Instant drag feedback** — Removed CSS transition from panel width so resize is immediate, not animated.
+- **Double-click to collapse** — Double-clicking the splitter toggles the context panel between 50% width and fully collapsed.
+- **Click-when-collapsed to expand** — If the context panel is collapsed, clicking the splitter expands it back to 50% without starting a drag.
+- **Hover-only scrollbars** — Scrollbars are hidden by default and appear as thin 6px tracks on hover (macOS overlay style). Applied to the context panel.
+- **Theme persistence across all entry points** — Extracted shared helpers `enrichWithThemeSettings()`, `createThemeSaver()`, and `runAskUserWithTheme()` in `index.ts`. All three entry points (`ask_user` tool, `/ask`, `/ask-debug`) now share identical theme read/save behavior.
+- **Type-safe theme settings** — `getThemeSettings()` now validates stored strings against `ThemeMode`/`AnimationLevel` union types before returning.
+- **Refactored constants** — Extracted `STOPWORDS` (~200 words) and `PROTECTED_ABBREVIATIONS` to `constants/stopwords.ts` and `constants/abbreviations.ts`.
+- **Fully controlled AdditionalComments** — Removed half-controlled anti-pattern. Component now requires both `value` and `onChange` props.
+- **Command rename** — `/ask-last` → `/ask` (shorter, more intuitive).
+
+### Fixed
+- **Mermaid rendering errors** — Added explicit `mermaid.initialize()` with `startOnLoad: false`. Defers `mermaid.run()` to `requestAnimationFrame` so the DOM is fully committed first. Errors now log via `console.warn` instead of being silently swallowed.
+- **Stale closure in keydown handlers** — SingleSelect and MultiSelect now use a `stateRef` pattern: all mutable state is snapshotted into a ref, and the global keydown listener has stable dependencies (`useCallback` for handlers).
+- **Short questions dropped** — `extractQuestions()` length threshold lowered from 10 to 3 characters so legitimate questions like "Why?" are not silently discarded.
+- **ARIA on splitter** — Added `role="separator"`, `aria-orientation="vertical"`, `aria-valuenow/min/max`.
+- **Option ref mutation** — Removed direct `optionRefs.current = []` mutation; uses `requestAnimationFrame` for focus timing instead.
+- **Consistent sendCancelled references** — All cancel buttons now pass `sendCancelled` directly instead of arrow wrappers.
+
+### Added
+- **`npm run test:with-context`** — New script that opens a WebView with the context panel, splitter, and Mermaid diagrams for visual testing.
+- **`webview/src/util/html.ts`** — Shared HTML utilities: `escapeHtml()` and `highlightMatch()`.
+
+## [0.4.0] — 2026-05-20
+
+### Added
+- **Branded header bar** — A thin branded bar at the top of every dialog with a sparkle icon + "Ask User" label on the left, and a settings cog + keyboard-shortcuts help on the right.
+- **Theme toggle (dark / light / system)** — Settings dropdown lets users switch between dark mode, light mode, or following the OS preference. Choice is persisted in the webview's localStorage.
+- **Animation level toggle (none / minimal / all)** — Settings dropdown also controls animation intensity. "None" disables all transitions; "minimal" keeps only essential ones; "all" enables full polish.
+- **Consistent Cmd+Enter submit** — All four dialog types (single-select, multi-select, questionnaire, freeform) now support Cmd+Enter (macOS) / Ctrl+Enter (other) to submit the answer. Footer hints updated accordingly.
+- **Window titles with session name** — Titles now read "Pi · {sessionName} · {question}" when a session name is set, making it easier to identify which conversation a dialog belongs to.
+- **Character counter** — Freeform textareas and questionnaire freeform fields show a live `0/2000` or `0/1000` counter. Turns red when approaching the limit.
+- **Required field badge** — In questionnaire mode, when `allowSkip: false`, unanswered questions show a red "Required" badge and a subtle red border until answered.
+- **Search highlight** — When filtering options via the search box, matching text in option titles and descriptions is highlighted with a yellow background.
+- **Quick-select all/none** — Multi-select dialogs show "Select all" and "Select none" links above the option list (when not actively searching).
+- **Keyboard shortcuts legend** — A `?` button in the header bar opens a modal showing all available keyboard shortcuts.
+
+### Changed
+- **CSS dark mode strategy** — Switched from `prefers-color-scheme` media query to Tailwind's `darkMode: 'class'` strategy, enabling explicit theme toggling independent of OS setting.
+- **Theme metadata in results** — The webview sends back the active theme and animation level with every result, so the extension can persist preferences across sessions.
+
+### Fixed
+- **White screen on /ask-debug** — The Glimpse native webview (WKWebView) blocks `localStorage` access with `SecurityError: The operation is insecure.` because `loadHTMLString(baseURL: nil)` gives the page no origin. Removed all `localStorage` usage from the webview entirely. Theme and animation state now flows through the payload: the extension reads stored settings from Pi journal entries, passes them into the webview via `AskUserPayload`, and the webview sends back the user's choices via the result's `__theme`/`__animationLevel` fields. The extension then persists them back into journal entries.
+- **Top-level ErrorBoundary** — Wrapped the entire React app in an `ErrorBoundary` so future render crashes show a readable error message instead of an empty white screen.
+
+## [0.3.2] — 2026-05-20
+
+### Fixed
+- **Recover all fixes lost during cherry-pick** — When cherry-picking the mermaid commit onto main, the jj colocated working copy was silently reset, discarding every other fix. This release restores: empty submit, shared icons/components, additional comments, auto-split logic, questionnaire focus fix, and updated prompt guidelines.
+
 ## [0.3.1] — 2026-05-20
 
 ### Fixed

package/CONTRIBUTING.md

@@ -20,8 +20,9 @@ npm run check        # dry-run npm pack
 ## Testing
 
 ```bash
-npm run validate     # checks dist exists, placeholder present, binary found
-npm run validate:gui # same + opens actual WebView for visual check
+npm run validate           # checks dist exists, placeholder present, binary found
+npm run validate:gui       # same + opens actual WebView for visual check
+npm run test:with-context  # opens WebView with context panel + resizable splitter
 npx tsx scripts/smoke-test.ts     # opens WebView for 2s
 npx tsx scripts/visual-qa.ts      # cycles through all 5 scenarios
 ```
@@ -33,8 +34,9 @@ npx tsx scripts/visual-qa.ts      # cycles through all 5 scenarios
 - **Console output:** Use `[pi-ask-user-glimpse]` prefix for all `console.warn`/`console.error`
 - **Peer deps:** Only list `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai` in `peerDependencies`
 
-## Security Note
+## Security Notes
 
+### HTML escaping in payload injection
 If you modify payload injection or test scripts, ensure HTML escaping matches production:
 ```ts
 JSON.stringify(payload)
@@ -43,9 +45,16 @@ JSON.stringify(payload)
   .replace(/&/g, "\\u0026")
 ```
 
+### XSS prevention in search highlighting
+`highlightMatch()` in `webview/src/util/html.ts` must escape both display text and search query before producing HTML. Never pass raw user input into `dangerouslySetInnerHTML`.
+
+### ContextPanel sanitization
+`sanitizeHtml()` blocks dangerous tags (`script`, `img`, `iframe`, `object`, `embed`, `form`, `svg`, etc.) and strips `javascript:` / `data:` URLs. Audit the sanitizer when adding new rich content support.
+
 ## Before Submitting
 
 - [ ] `npm run build` passes
 - [ ] `npx tsc --noEmit` passes
-- [ ] `npm run check` shows the expected files
+- [ ] `npm run check` shows the expected files (including `constants/`)
 - [ ] `npm run validate` passes
+- [ ] `npm run test:with-context` passes

package/README.md

@@ -30,10 +30,14 @@ The agent gets a clean selection back. You get a decision made in seconds, not m
 
 ## Features
 
-- **Single-select** — searchable option list with inline descriptions
-- **Multi-select** — checkbox-style selection with submit/cancel
-- **Freeform** — textarea input for open-ended responses
-- **Questionnaire** — cards in a vertical list for structured questions, each with its own options
+- **Single-select** — searchable option list with inline descriptions and search highlight
+- **Multi-select** — checkbox-style selection with quick-select all/none links
+- **Freeform** — textarea input with live character counter and platform-aware keyboard shortcuts
+- **Questionnaire** — cards in a vertical list for structured questions, with required-field badges and per-question character counters
+- **Theme toggle** — dark / light / system mode switcher in the dialog header
+- **Animation levels** — none / minimal / all, controlling transition intensity across the UI
+- **Keyboard shortcuts legend** — press `?` in the header bar to see all available shortcuts
+- **Prominent question header** — full non-truncated question text in the header bar, with settings cog and keyboard-shortcuts help
 - **Native WebView** — renders in a real window (macOS WKWebView / Linux GTK4 / Windows WebView2)
 - **Terminal fallback** — gracefully degrades to TUI prompts when glimpseui is unavailable
 
@@ -67,7 +71,7 @@ Ask the user to pick exactly one option:
 }
 ```
 
-The dialog shows a full-width question header and a two-panel layout. When `context` is provided, the left panel renders it as markdown for reference while the right panel shows the searchable option list. Option descriptions appear inline below each title. The "Custom" button under the search box lets the user submit a freeform answer.
+The dialog shows the full question in the header bar, and a two-panel layout when `context` is provided. The left panel renders context as markdown (with Mermaid diagram support) while the right panel shows the searchable option list. The panels are resizable via a drag handle on the boundary — double-click the handle to collapse the context panel. Option descriptions appear inline below each title, and matching text is highlighted when searching. The "Custom" button lets the user submit a freeform answer. Use ⌘+Enter (macOS) or Ctrl+Enter to submit.
 
 ### Multi Select
 
@@ -88,7 +92,7 @@ Ask the user to pick multiple options:
 }
 ```
 
-Each option has a checkbox. A "Clear all" link resets selections. Submit is disabled until at least one item is selected.
+Each option has a checkbox. "Select all" and "Select none" links appear above the list (when not searching). A "Clear all" link resets selections. Submit is disabled until at least one item is selected. Use ⌘+Enter (macOS) or Ctrl+Enter to submit.
 
 ### Freeform
 
@@ -102,7 +106,7 @@ Ask an open-ended question with no predefined options:
 }
 ```
 
-Shows a full-height textarea with platform-aware keyboard hints (⌘+Enter on macOS, Ctrl+Enter elsewhere). Submit is disabled until text is entered.
+Shows a full-height textarea with a live character counter and platform-aware keyboard hints (⌘+Enter on macOS, Ctrl+Enter elsewhere). Submit is disabled until text is entered.
 
 ### Questionnaire
 
@@ -140,7 +144,7 @@ Ask multiple structured questions in one dialog:
 }
 ```
 
-Each question is shown as a card with a progress bar at the top. Questions with `options` render as single-select (radio) or multi-select (checkbox) depending on `allowMultiple`. Questions without `options` render as a textarea. The dialog auto-scrolls to the first unanswered question on open. The comment button shows "Edit comment" when text exists. Submit is disabled until all questions have a non-empty answer, unless `allowSkip: true` is set.
+Each question is shown as a card with a progress bar at the top. Questions with `options` render as single-select (radio) or multi-select (checkbox) depending on `allowMultiple`. Questions without `options` render as a textarea with a character counter. The dialog auto-scrolls to the first unanswered question on open. When `allowSkip: false`, unanswered questions show a red "Required" badge. The comment button shows "Edit comment" when text exists. Submit is disabled until all questions have a non-empty answer, unless `allowSkip: true` is set. Use ⌘+Enter (macOS) or Ctrl+Enter to submit.
 
 ### Parameters
 
@@ -223,12 +227,12 @@ The setting is persisted in the session and survives restarts.
 
 The injected mandate is ~100 tokens. It is only appended when detection triggers, so normal conversations pay nothing extra.
 
-## Slash Command: `/ask-last`
+## Slash Command: `/ask`
 
 When the assistant writes a question as free-form text (bypassing `ask_user`), use this command to retroactively open the rich dialog:
 
 ```
-/ask-last
+/ask
 ```
 
 ### How it works
@@ -256,22 +260,26 @@ Options: `single-select`, `multi-select`, `freeform`, `questionnaire`. The resul
 
 ## Window Behavior
 
-- **Title bar** — shows a condensed version of the question text (up to 3 content words)
+- **Title bar** — reads "Pi · {sessionName} · {question}" (session name is included when set)
 - **Centered dialog** — normal stacking, not floating
 - **Size** — 1200×900 by default
+- **Context panel** — 50/50 split by default; drag the handle to resize, double-click to collapse
+- **Scrollbars** — hidden by default, appear on hover (macOS-style overlay)
 - **Cursor follow** — off by default; enable with `followCursor: true`
-- **Dark mode** — automatically follows the system `prefers-color-scheme` setting
+- **Dark mode** — togglable via the settings cog: dark, light, or system (follows OS preference)
+- **Theme persistence** — theme and animation choices survive across dialogs and session restarts
 
 ## Architecture
 
 ```
 index.ts              → Pi extension entrypoint (tool + command registration)
+constants/            → STOPWORDS, PROTECTED_ABBREVIATIONS
 tool/ask-user.ts      → constructs payload, injects into HTML, calls glimpseui.prompt()
 tool/response-formatter.ts → normalizes WebView response for Pi
-webview/src/components/     → SingleSelect, MultiSelect, Questionnaire, Freeform, ContextPanel, ErrorBoundary
 fallback/terminal-prompt.ts → readline fallback when WebView unavailable
 webview/              → Vite + React + Tailwind app
-  src/components/     → SingleSelect, MultiSelect, Questionnaire, Freeform
+  src/components/     → SingleSelect, MultiSelect, Questionnaire, Freeform, ContextPanel, ErrorBoundary, HeaderBar, ShortcutsModal, AdditionalComments
+  src/util/           → settings.tsx (theme/animation context), glimpse.ts (host bridge), platform.ts (modKey), html.ts (escapeHtml + highlightMatch)
   dist/index.html     → single-file bundle (inlined JS + CSS)
 ```
 

package/constants/abbreviations.ts

@@ -0,0 +1,6 @@
+/** Protected abbreviations for sentence splitting. */
+export const PROTECTED_ABBREVIATIONS = new Set([
+    "etc", "vs", "fig", "dr", "mr", "mrs", "ms", "prof", "jr", "sr",
+    "inc", "ltd", "corp", "co", "llc", "al", "et", "vol", "vols",
+    "pg", "pp", "ch", "chap", "sec", "secs",
+]);

package/constants/stopwords.ts

@@ -0,0 +1,42 @@
+/** ~200 common English stopwords for title extraction. */
+export const STOPWORDS = new Set([
+    "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "could",
+    "should", "may", "might", "must", "shall", "can", "need", "ought",
+    "used", "to", "of", "in", "for", "on", "with", "at", "by", "from",
+    "as", "into", "through", "during", "before", "after", "above",
+    "below", "between", "under", "again", "further", "then", "once",
+    "here", "there", "when", "where", "why", "how", "all", "each",
+    "few", "more", "most", "other", "some", "such", "no", "nor", "not",
+    "only", "own", "same", "so", "than", "too", "very", "just", "and",
+    "but", "if", "or", "because", "until", "while", "which", "what",
+    "who", "whom", "this", "that", "these", "those", "am", "it", "its",
+    "we", "our", "you", "your", "they", "their", "them", "he", "him",
+    "his", "she", "her", "i", "me", "my", "mine", "us", "any", "both",
+    "either", "neither", "one", "two", "first", "last", "another",
+    "every", "many", "much", "several", "let", "new", "use", "using",
+    "make", "made", "get", "got", "go", "going", "want", "wanted", "like",
+    "liked", "know", "knew", "known", "think", "thought", "see", "saw",
+    "seen", "come", "came", "give", "gave", "given", "take", "took",
+    "taken", "find", "found", "say", "said", "tell", "told", "ask",
+    "asked", "work", "worked", "seem", "seemed", "feel", "felt", "try",
+    "tried", "leave", "left", "call", "called", "good", "well", "better",
+    "best", "bad", "worse", "worst", "old", "long", "great", "little",
+    "right", "left", "big", "high", "different", "important", "same",
+    "able", "next", "early", "young", "public", "free", "real", "easy",
+    "clear", "recent", "local", "social", "full", "small", "large",
+    "possible", "particular", "available", "special", "certain", "personal",
+    "open", "general", "enough", "probably", "actually", "especially",
+    "finally", "usually", "perhaps", "almost", "simply", "quickly",
+    "recently", "already", "eventually", "suddenly", "certainly",
+    "definitely", "absolutely", "completely", "totally", "entirely",
+    "exactly", "specifically", "particularly", "especially", "mainly",
+    "mostly", "partly", "fully", "nearly", "quite", "rather", "pretty",
+    "fairly", "really", "even", "still", "yet", "ever", "never", "always",
+    "sometimes", "often", "usually", "frequently", "rarely", "generally",
+    "typically", "normally", "largely", "potentially", "theoretically",
+    "practically", "basically", "essentially", "fundamentally",
+    "primarily", "chiefly", "principally", "partially", "half", "quarter",
+    "double", "single", "multiple", "various", "hundred", "thousand",
+    "million", "billion",
+]);