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

package/CHANGELOG.md

@@ -2,13 +2,36 @@
 
 All notable changes to `@alexleekt/pi-ask-user-glimpse` are documented in this file.
 
-## [Unreleased]
+## [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
 

package/CONTRIBUTING.md

@@ -23,10 +23,10 @@ npm run check        # dry-run npm pack
 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
 ```
 
+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)

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,16 +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 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
+- **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
 
@@ -94,6 +96,28 @@ Ask the user to pick multiple options:
 
 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
 
 Ask an open-ended question with no predefined options:
@@ -106,7 +130,7 @@ Ask an open-ended question with no predefined options:
 }
 ```
 
-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.
+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
 
@@ -151,8 +175,9 @@ Each question is shown as a card with a progress bar at the top. Questions with
 | 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 |
@@ -189,43 +214,37 @@ 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`
 
@@ -256,7 +275,9 @@ 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
 
@@ -276,7 +297,7 @@ 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
-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, ContextPanel, ErrorBoundary, HeaderBar, ShortcutsModal, AdditionalComments
   src/util/           → settings.tsx (theme/animation context), glimpse.ts (host bridge), platform.ts (modKey), html.ts (escapeHtml + highlightMatch)
@@ -289,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"