@alexleekt/pi-ask-user-glimpse 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 All notable changes to `@alexleekt/pi-ask-user-glimpse` are documented in this file.
 
+## [0.5.0] — 2026-05-24
+
+### Added
+- **Kitchen-sink debug mode** — `/ask-debug` now includes a `kitchen-sink` option that opens a comprehensive questionnaire demonstrating every major feature in one dialog: HTML context panel, recommended badges, multi-select, single-select, freeform, comments, and skip. Replaces the previous 9-mode menu (which had 5 redundant single-select variations) with a clean 5-mode list.
+- **HTML context iframe sizing fix** — Removed `loading="lazy"` from the sandboxed iframe. Glimpse's native WebView host (WKWebView on macOS / WebView2 on Windows) applies lazy-loading heuristics even to `srcDoc` iframes with no network request, causing the HTML content to never render in some versions. Changed the iframe container from `overflow-y-auto` to `overflow-hidden flex flex-col` so the iframe's `flex-1` sizing works reliably within the flex layout. The iframe now uses `flex-1 min-h-0` instead of `h-full` to avoid the 150px default-height fallback when percentage heights fail in nested flex contexts.
+- **Recommendation badges** — Options can now include `recommended: true` to show a "Recommended" badge in the dialog. The badge renders next to the option title using the primary color token. Works in single-select, multi-select, and questionnaire modes. The LLM tool schema documents the field so agents can mark their top recommendation.
+- **Option numbering** — Each option now displays a circular number badge (① ② ③…) between the checkbox/radio and the title text. Provides a quick visual reference for keyboard navigation and makes it easier to refer to options when discussing choices.
+- **Markdown rendering in option text** — Option titles and descriptions are now rendered through inline markdown. Bold `**`, italic `*`, code `` ` ``, and links display correctly. During search, markdown rendering is temporarily disabled to avoid broken markup from injected `<mark>` highlight tags.
+- ~~Auto-catch free-form questions~~ — **Removed.** The "Always Dialog" mode and its auto-catch behavior have been eliminated.
+- **HTML context format** — New `contextFormat: "html"` option for the `ask_user` tool. When set, the `context` field renders inside a sandboxed iframe (`sandbox="allow-scripts"`) in the left panel instead of markdown. The iframe inherits the wrapper's CSS variables for automatic light/dark theme consistency. Theme changes are propagated via `postMessage`.
+- **YOLO style** — New `/ask-style` state that tells the agent to proceed with its best recommendation without asking. Injects a mandate: "Do NOT ask the user for input or confirmation. Go with your best recommendation and proceed immediately. Only use `ask_user` if the action would cause irreversible harm, data loss, security compromise, or violate explicit hard constraints."
+
+### Removed
+- **"Always Dialog" mode** — Removed the `ASK_USER_MANDATE` system-prompt injection and the auto-catch behavior that converted free-form agent questions into dialogs. These features caused excessive dialog interruptions and were too aggressive for general use. The `/ask` command and manual `ask_user` tool calls still work normally.
+
+### Changed
+- **Plain Text is now the default** — The extension no longer injects any system-prompt mandate by default. The agent writes questions as free-form text unless the user manually triggers `/ask` or the agent calls `ask_user`. The `/ask-style` toggle now cycles through **Plain Text** → **YOLO** → **Plain Text**.
+- **Two-state `/ask-style` cycle** — `Plain Text → YOLO → Plain Text`.
+- **`deliverAs: "steer"` for all user message delivery** — Both auto-catch and `/ask` now use `steer` instead of `followUp` when sending answers back to the conversation. `steer` sends immediately and is processed as an active user intervention, avoiding the "Follow-up: queued messages" UI state where the answer was stuck waiting.
+- **Removed terminal fallback** — Deleted `fallback/terminal-prompt.ts`. When the Glimpse native host is unavailable, the extension always returns an explicit error telling the agent to ask in free-form text. The previous TUI fallback (`ctx.ui.select()` / `ctx.ui.input()`) has been removed to simplify the codebase and provide consistent behavior.
+- **Freeform empty submissions allowed** — Removed the guard that blocked empty freeform text submissions. This is consistent with questionnaire behavior where unanswered questions are allowed when `allowSkip: true`.
+
+### 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`.
+- **`sendUserMessage` error handling** — Wrapped `pi.sendUserMessage()` in `try/catch` with `await` in the `/ask` handler. Previously, the promise was fire-and-forget; when the framework threw "Agent is already processing" (or any other error), the rejection was unhandled and the dialog answer was silently lost. Errors are now logged to console with `[pi-ask-user-glimpse]` prefix and surfaced via UI notification.
+- **`additionalComments` in questionnaire responses** — The `questionnaire` response kind was missing the `additionalComments` field that existed for `selection` and `freeform` kinds. Now all three kinds consistently include `additionalComments` when the user provides them.
+- **Fast-escape when no UI available** — `askUserHandler` now returns an explicit error message ("No UI available for ask_user dialog...") instead of falling back to a terminal prompt when `!ctx.hasUI`. The `before_agent_start` mandate injection is also skipped in headless environments, preventing the agent from being forced to use a tool that cannot work.
+
+## [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

package/CONTRIBUTING.md

@@ -20,12 +20,13 @@ 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
-npx tsx scripts/smoke-test.ts     # opens WebView for 2s
-npx tsx scripts/visual-qa.ts      # cycles through all 5 scenarios
+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
 ```
 
+For manual visual testing, use `/ask-debug` inside a Pi session. It offers five scenarios: `single-select`, `multi-select`, `freeform`, `questionnaire`, and `kitchen-sink` (comprehensive questionnaire with HTML context panel).
+
 ## Code Style
 
 - **Indentation:** 2 spaces (TypeScript)
@@ -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

@@ -1,9 +1,11 @@
 # @alexleekt/pi-ask-user-glimpse
 
-[![npm version](https://img.shields.io/npm/v/@alexleekt/pi-ask-user-glimpse.svg)](https://www.npmjs.com/package/@alexleekt/pi-ask-user-glimpse)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/@alexleekt/pi-ask-user-glimpse)](https://www.npmjs.com/package/@alexleekt/pi-ask-user-glimpse)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-A Pi extension that replaces `ask_user` with rich native WebView dialogs powered by [glimpseui](https://npmjs.com/package/glimpseui) and styled with shadcn/ui design tokens.
+> Ask better questions. Get better answers.
+
+Rich native WebView dialogs powered by [glimpseui](https://npmjs.com/package/glimpseui) and styled with shadcn/ui design tokens.
 
 > **Stop reading terminal walls of text.** This extension turns every `ask_user` call into a beautiful, searchable, keyboard-navigable dialog — complete with markdown context panels, inline descriptions, and dark mode. Your agent asks better questions. You answer faster.
 
@@ -30,12 +32,16 @@ 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, numbered option badges (① ② ③), inline markdown rendering, and search highlight
+- **Multi-select** — checkbox-style selection with quick-select all/none links, numbered badges, and inline markdown
+- **Freeform** — textarea input with live character counter and platform-aware keyboard shortcuts. Empty submissions are allowed (useful when the agent asks an open question but you have nothing to add)
+- **Questionnaire** — cards in a vertical list for structured questions, with required-field badges, per-question character counters, numbered option badges, and inline markdown in option text
+- **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
+- **Graceful degradation** — returns clear error when no UI is available, prompting the agent to ask in free-form text
 
 ## Install
 
@@ -67,7 +73,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 +94,29 @@ 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.
+
+### HTML Context (Visualizations)
+
+When text and Mermaid diagrams aren't enough, render rich HTML in the context panel:
+
+```json
+{
+  "question": "Which layout performs better?",
+  "context": "<div style='display:flex;gap:1rem;justify-content:center'>...</div>",
+  "contextFormat": "html",
+  "options": [
+    { "title": "Layout A", "description": "Dense grid with sidebar" },
+    { "title": "Layout B", "description": "Spacious single column" }
+  ]
+}
+```
+
+The `context` HTML renders inside a **sandboxed iframe** (`sandbox="allow-scripts"`) in the left panel. It inherits the wrapper's CSS variables (`--background`, `--foreground`, `--primary`, etc.) for automatic light/dark theme consistency. The iframe auto-updates its theme class when the user toggles settings. This is ideal for throwaway bar charts, tables, decision trees, or any visualization that helps the user decide.
+
+**Security:** The iframe is isolated from the wrapper app. It cannot access `localStorage`, cookies, or the parent DOM. Only inline scripts are permitted (for animations/interactivity). The agent should not include `<script src="...">` tags that load external resources — inline JS and CSS only.
+
+**Glimpse behavior:** The HTML context panel runs inside Glimpse's native WebView host (WKWebView on macOS, WebView2 on Windows). The iframe receives an opaque ("null") origin because Glimpse loads the page via `loadHTMLString` without a base URL. This means `window.location.origin` is `null`, and `localStorage` access throws a `SecurityError`. Theme changes are propagated via `postMessage` instead of DOM sharing.
 
 ### Freeform
 
@@ -102,7 +130,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 always enabled — you can send an empty answer if you have nothing to add.
 
 ### Questionnaire
 
@@ -140,15 +168,16 @@ 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
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `question` | `string` | *(required)* | The question to ask |
-| `context` | `string` | — | Additional context shown in a left-side markdown panel |
-| `options` | `Array<string &#124; {title, description?}>` | — | Options for flat single/multi-select mode |
+| `context` | `string` | — | Additional context shown in a left-side panel |
+| `contextFormat` | `"markdown" &#124; "html"` | `"markdown"` | Format of the `context` field. `markdown` renders formatted text with Mermaid diagram support. `html` renders in a sandboxed iframe — useful for throwaway charts, tables, or interactive visualizations. The iframe inherits the wrapper's CSS variables for theme consistency. |
+| `options` | `Array<string &#124; {title, description?, recommended?}>` | — | Options for flat single/multi-select mode. Set `recommended: true` to show a "Recommended" badge. |
 | `questions` | `Array<{title, description?, options?, allowMultiple?}>` | — | Questions for questionnaire mode. When present, `options` is ignored. Each question can have its own `options` (same shape as top-level `options`) and `allowMultiple`. Questions without `options` render as freeform textareas. |
 | `allowMultiple` | `boolean` | `false` | Allow selecting multiple options |
 | `allowFreeform` | `boolean` | `true` | Show a freeform "Custom" option |
@@ -185,50 +214,44 @@ npm run validate:gui # same + opens actual WebView for visual check
 npm run check        # dry-run npm pack
 ```
 
-## Auto-Detection: When `ask_user` Is Used Automatically
+## Ask-Style Toggle: `/ask-style`
 
-Some skills instruct the agent to "ask questions one at a time" but never tell it to **use a tool** — so the agent writes plain text, bypassing the rich WebView dialog.
+By default, the agent asks questions as free-form text. You can change this per-session:
 
-This extension auto-detects question-oriented sessions and injects a system-prompt mandate that tells the LLM to use `ask_user` for every question.
+```
+/ask-style
+```
 
-### Auto-detection
+Cycles through two states:
 
-Before each LLM turn, the extension checks:
+| State | Behavior |
+|-------|----------|
+| **Plain Text** *(default)* | Agent writes questions as free-form text |
+| **YOLO** | Agent proceeds with its best recommendation without asking |
 
-1. **Known question skills** — `grill-with-docs`, `questionnaire`, `interview`, `grill`
-2. **Language patterns** in the system prompt — "ask the questions one at a time", "interview me", "grilling session", "wait for feedback"
-3. **Manual toggle** — `/ask-style` overrides the behavior for the current session
+The setting is persisted in the session and survives restarts.
 
-When triggered, it appends: "You MUST use `ask_user` for every question. Do NOT write free-form text."
+### YOLO style
 
-### Manual toggle: `/ask-style`
+When YOLO is active, the extension injects a mandate telling the agent **not** to ask for input or confirmation. Instead, the agent goes with its best recommendation and keeps moving. It will only use `ask_user` if the action would cause irreversible harm, data loss, or security compromise.
 
-Override auto-detection for the current session:
+Use this when you trust the agent's judgment and want maximum speed:
 
 ```
 /ask-style
+→ ask_user style: YOLO — go with your recommendation
 ```
 
-Cycles through three states:
-
-| State | Behavior |
-|-------|----------|
-| **AUTO** *(default)* | Auto-detect question sessions by skill name + language patterns |
-| **Always Dialog** | Always use `ask_user` for every question, regardless of detection |
-| **Plain Text** | Disable everything — let the agent write questions as plain text |
-
-The setting is persisted in the session and survives restarts.
-
 ### Token cost
 
-The injected mandate is ~100 tokens. It is only appended when detection triggers, so normal conversations pay nothing extra.
+The injected mandate is ~100 tokens. It is appended on every turn when `ask_user` is available in the tool set.
 
-## 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
@@ -252,26 +275,32 @@ Open a debug prompt that lets you manually test each dialog type:
 /ask-debug
 ```
 
-Options: `single-select`, `multi-select`, `freeform`, `questionnaire`. The result is shown as a Pi notification.
+Options: `single-select`, `multi-select`, `freeform`, `questionnaire`, `kitchen-sink`. The result is shown as a Pi notification.
+
+The **kitchen-sink** option opens a comprehensive questionnaire with an HTML context panel, recommended badges, multi-select, freeform, comments, and skip — every major feature in one dialog.
 
 ## 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
+(no terminal fallback — fast-escape with error when UI 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)
 ```
 
@@ -281,9 +310,9 @@ webview/              → Vite + React + Tailwind app
 
 Run `npm run build` to generate `dist/index.html`. The extension cannot work without the webview bundle.
 
-### WebView does not open (terminal fallback instead)
+### WebView does not open
 
-The extension falls back to TUI prompts when the glimpseui native host is unavailable. This is normal on headless systems or if the native binary is missing. Check `npm run validate` to see if the binary is detected.
+If the glimpseui native host is unavailable, the extension returns an error to the agent, which will ask the question in free-form text instead. This is normal on headless systems or if the native binary is missing. Check `npm run validate` to see if the binary is detected.
 
 ### Dialog shows "Missing or invalid ask_user payload"
 

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",
+]);