pi-interview 0.4.5 → 0.5.2

package/README.md

@@ -4,7 +4,7 @@
 
 # Interview Tool
 
-A custom tool for pi-agent that opens a web-based form to gather user responses to clarification questions.
+A custom tool for pi-agent that opens an interactive form to gather user responses to clarification questions. On macOS, uses [Glimpse](https://github.com/hazat/glimpse) to render in a native WKWebView window; falls back to a browser tab on other platforms.
 
 https://github.com/user-attachments/assets/52285bd9-956e-4020-aca5-9fbd82916934
 
@@ -18,10 +18,14 @@ Restart pi to load the extension.
 
 **Requirements:**
 - pi-agent v0.35.0 or later (extensions API)
+- For native macOS window: `pi install npm:glimpseui` (optional, falls back to browser if not installed)
 
 ## Features
 
-- **Question Types**: Single-select, multi-select, text input, and image upload
+- **Question Types**: Single-select, multi-select, text input, image upload, and info panels
+- **Rich Media**: Embed images, Chart.js charts, Mermaid diagrams, tables, and HTML in questions
+- **Pre-selection**: Recommended options show a "Recommended" badge and are pre-checked on load
+- **Conviction & Weight**: Control recommendation strength (`conviction`) and visual prominence (`weight`)
 - **"Other" Option**: Single/multi select questions support custom text input
 - **Per-Question Attachments**: Attach images to any question via button, paste, or drag & drop
 - **Keyboard Navigation**: Full keyboard support with arrow keys, Tab, Enter
@@ -40,7 +44,7 @@ Restart pi to load the extension.
 
 ```
 ┌─────────┐      ┌──────────────────────────────────────────┐      ┌─────────┐
-│  Agent  │      │              Browser Form                │      │  Agent  │
+│  Agent  │      │        Glimpse / Browser Form             │      │  Agent  │
 │ invokes ├─────►│                                          ├─────►│receives │
 │interview│      │  answer → answer → attach img → answer   │      │responses│
 └─────────┘      │     ↑                                    │      └─────────┘
@@ -49,7 +53,7 @@ Restart pi to load the extension.
 ```
 
 **Lifecycle:**
-1. Agent calls `interview()` → local server starts → browser opens form
+1. Agent calls `interview()` → local server starts → Glimpse window opens (macOS) or browser tab (elsewhere)
 2. User answers at their own pace; each change auto-saves and resets the timeout
 3. Session ends via:
    - **Submit** (`⌘+Enter`) → responses returned to agent
@@ -59,7 +63,7 @@ Restart pi to load the extension.
 
 **Timeout behavior:** The countdown (visible in corner) resets on any activity - typing, clicking, or mouse movement. When it expires, an overlay appears giving the user a chance to continue. Progress is never lost thanks to localStorage auto-save.
 
-**Multi-agent behavior:** When multiple agents run interviews simultaneously, only the first auto-opens the browser. Subsequent interviews are queued and shown as a URL in the tool output, preventing focus stealing. Active interviews also surface a top-right toast with a dropdown to open queued sessions. A session status bar at the top of each form shows the project path, git branch, and session ID for easy identification.
+**Multi-agent behavior:** When multiple agents run interviews simultaneously, only the first auto-opens the window. Subsequent interviews are queued and shown as a URL in the tool output, preventing focus stealing. Active interviews also surface a top-right toast with a dropdown to open queued sessions. A session status bar at the top of each form shows the project path, git branch, and session ID for easy identification.
 
 ## Usage
 
@@ -79,14 +83,22 @@ await interview({
 ```json
 {
   "title": "Project Setup",
-  "description": "Optional description text",
+  "description": "Review my suggestions and adjust as needed.",
   "questions": [
+    {
+      "id": "context",
+      "type": "info",
+      "question": "Architecture context",
+      "context": "This project needs SSR and edge deployment support."
+    },
     {
       "id": "framework",
       "type": "single",
       "question": "Which framework?",
       "options": ["React", "Vue", "Svelte"],
-      "recommended": "React"
+      "recommended": "React",
+      "conviction": "strong",
+      "weight": "critical"
     },
     {
       "id": "features",
@@ -96,6 +108,14 @@ await interview({
       "options": ["Auth", "Database", "API"],
       "recommended": ["Auth", "Database"]
     },
+    {
+      "id": "indent",
+      "type": "single",
+      "question": "Indent style?",
+      "options": ["Tabs", "Spaces (2)", "Spaces (4)"],
+      "recommended": "Spaces (2)",
+      "weight": "minor"
+    },
     {
       "id": "notes",
       "type": "text",
@@ -115,12 +135,15 @@ await interview({
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | string | Unique identifier |
-| `type` | string | `single`, `multi`, `text`, or `image` |
+| `type` | string | `single`, `multi`, `text`, `image`, or `info` |
 | `question` | string | Question text |
 | `options` | string[] or object[] | Choices (required for single/multi). Can be strings or `{ label, code? }` objects |
-| `recommended` | string or string[] | Highlighted option(s) with `*` indicator |
+| `recommended` | string or string[] | Shows "Recommended" badge and pre-selects option(s) |
+| `conviction` | string | `"strong"` or `"slight"`. Slight opts out of pre-selection. Requires `recommended` |
+| `weight` | string | `"critical"` (prominent card) or `"minor"` (compact card) |
 | `context` | string | Help text shown below question |
 | `codeBlock` | object | Code block displayed below question text |
+| `media` | object or object[] | Media content: image, chart, mermaid, table, or html |
 
 ### Code Blocks
 
@@ -182,6 +205,64 @@ Questions and options can include code blocks for displaying code snippets, diff
 
 Line numbers are shown when `file` or `lines` is specified. Diff syntax (`+`/`-` lines) is automatically styled when `lang` is "diff".
 
+### Info Panels
+
+Use `type: "info"` for non-interactive context panels. They display a title, context text, and optional media but have no input — they're skipped during keyboard navigation and excluded from responses.
+
+```json
+{
+  "id": "overview",
+  "type": "info",
+  "question": "Architecture Overview",
+  "context": "The system uses a microservices architecture with three main services.",
+  "media": { "type": "mermaid", "mermaid": "graph LR\n  A[API] --> B[Auth]\n  A --> C[Data]" }
+}
+```
+
+### Media Blocks
+
+Questions can embed media via the `media` field (single object or array). Supported types:
+
+| Type | Fields | Description |
+|------|--------|-------------|
+| `image` | `src`, `alt?`, `caption?` | Image (local path, URL, or data URI) |
+| `table` | `table: { headers, rows, highlights? }`, `caption?` | Data table with optional row highlighting |
+| `chart` | `chart: { type, data, options? }`, `caption?` | Chart.js chart (bar, line, pie, etc.) |
+| `mermaid` | `mermaid: "graph LR\n..."`, `caption?` | Mermaid diagram |
+| `html` | `html: "<div>...</div>"`, `caption?` | Raw HTML content |
+
+All media types support `position`: `"above"` (default), `"below"`, or `"side"` (two-column layout).
+
+```json
+{
+  "id": "db-choice",
+  "type": "single",
+  "question": "Which database?",
+  "media": {
+    "type": "table",
+    "table": {
+      "headers": ["Database", "Latency", "Cost"],
+      "rows": [["PostgreSQL", "~5ms", "$50/mo"], ["DynamoDB", "~2ms", "$80/mo"]],
+      "highlights": [0]
+    },
+    "caption": "Benchmark results from staging"
+  },
+  "options": ["PostgreSQL", "DynamoDB"],
+  "recommended": "PostgreSQL"
+}
+```
+
+### Conviction & Weight
+
+**Conviction** controls how strongly a recommendation is presented:
+- Omitted (default): shows "Recommended" badge, pre-selects the option
+- `"strong"`: same as default (use when very confident)
+- `"slight"`: shows "Recommended" badge but does NOT pre-select (use when unsure)
+
+**Weight** controls visual prominence:
+- `"critical"`: thick accent border, tinted background — for decisions that matter most
+- `"minor"`: compact card with smaller text and padding — for low-stakes preferences
+
 ## Keyboard Shortcuts
 
 | Key | Action |
@@ -240,7 +321,7 @@ The interview form supports light/dark themes with automatic OS detection and us
 | Theme | Description |
 |-------|-------------|
 | `default` | Monospace, IDE-inspired aesthetic |
-| `tufte` | Serif fonts (Cormorant Garamond), book-like feel |
+| `tufte` | Serif fonts (Instrument Serif), book-like feel |
 
 ### Theme Modes
 

package/form/index.html

@@ -4,6 +4,9 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Interview</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;600;700&family=Space+Mono:wght@400;700&family=Instrument+Serif&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
   <link rel="stylesheet" href="/styles.css?session=__SESSION_TOKEN__">
   <link rel="stylesheet" href="/theme-light.css?session=__SESSION_TOKEN__" data-theme-link="light" media="(prefers-color-scheme: light)">
   <link rel="stylesheet" href="/theme-dark.css?session=__SESSION_TOKEN__" data-theme-link="dark" media="(prefers-color-scheme: dark)">
@@ -57,9 +60,8 @@
         <span class="shortcut-label">Cancel</span>
       </div>
       <div class="shortcut-divider"></div>
-      <div class="shortcut recommended-hint">
-        <span class="shortcut-keys"><span class="star">*</span></span>
-        <span class="shortcut-label">Recommended</span>
+      <div class="shortcut">
+        <span class="recommended-pill">Recommended</span>
       </div>
       <div class="shortcut hidden" data-theme-shortcut>
         <span class="shortcut-keys" data-theme-keys></span>
@@ -115,6 +117,7 @@
     <div id="save-toast" class="save-toast hidden" aria-live="polite"></div>
   </main>
 
+  <!-- __CDN_SCRIPTS__ -->
   <script>
     window.__INTERVIEW_DATA__ = /* __INTERVIEW_DATA_PLACEHOLDER__ */;
   </script>