pi-ui-extend 1.0.38 → 1.0.39

package/dist/bundled-extensions/question/tui.js

@@ -171,20 +171,48 @@ export async function runQuestionnaire(questions, ctx) {
         function captureCustomDraft() {
             if (mode !== "custom")
                 return;
-            customDrafts.set(currentQuestion().id, sharedEditorSnapshot());
+            const question = currentQuestion();
+            const snapshot = sharedEditorSnapshot();
+            customDrafts.set(question.id, snapshot);
+            if (question.multiple) {
+                const existing = multipleSelection(question);
+                selections.set(question.id, {
+                    id: question.id,
+                    choiceValues: existing.choiceValues,
+                    customText: snapshot.text,
+                    ...(snapshot.images.length > 0 ? { images: snapshot.images } : {}),
+                });
+            }
+        }
+        function multipleSelection(question) {
+            const existing = selections.get(question.id);
+            return existing && "choiceValues" in existing ? existing : { id: question.id, choiceValues: [] };
+        }
+        function selectionIsComplete(question, selection) {
+            if (!selection)
+                return false;
+            if (!question.multiple)
+                return !("choiceValues" in selection);
+            if (!("choiceValues" in selection))
+                return false;
+            const hasCustom = selection.customText !== undefined;
+            if (hasCustom && !selection.customText?.trim() && (selection.images?.length ?? 0) === 0)
+                return false;
+            const count = selection.choiceValues.length + (hasCustom ? 1 : 0);
+            return count >= (question.minSelections ?? 1) && count <= (question.maxSelections ?? question.choices.length + 1);
         }
         function getCompleteSelections() {
             const orderedSelections = [];
             for (const question of questions) {
                 const selection = selections.get(question.id);
-                if (!selection)
+                if (!selection || !selectionIsComplete(question, selection))
                     return undefined;
                 orderedSelections.push(selection);
             }
             return orderedSelections;
         }
         function firstUnansweredIndex() {
-            return questions.findIndex((question) => !selections.has(question.id));
+            return questions.findIndex((question) => !selectionIsComplete(question, selections.get(question.id)));
         }
         function submitCompleteSelections() {
             const completeSelections = getCompleteSelections();
@@ -200,6 +228,18 @@ export async function runQuestionnaire(questions, ctx) {
             submitCompleteSelections();
         }
         function formatReviewAnswerLabel(question, selection) {
+            if ("choiceValues" in selection) {
+                const labels = question.choices
+                    .filter((choice) => selection.choiceValues.includes(choice.value))
+                    .map((choice) => choice.label);
+                if (selection.customText !== undefined) {
+                    const imageCount = selection.images?.length ?? 0;
+                    const text = selection.customText.trim() || formatAttachedImages(imageCount);
+                    const imageSuffix = selection.customText.trim() && imageCount > 0 ? ` (+${formatAttachedImages(imageCount)})` : "";
+                    labels.push(`${CUSTOM_ANSWER_LABEL}: ${text}${imageSuffix}`);
+                }
+                return labels.join(", ") || "Unanswered";
+            }
             if ("customText" in selection) {
                 const imageCount = selection.images?.length ?? 0;
                 const text = selection.customText || formatAttachedImages(imageCount);
@@ -212,6 +252,12 @@ export async function runQuestionnaire(questions, ctx) {
             const selection = selections.get(question.id);
             if (!selection)
                 return 0;
+            if ("choiceValues" in selection) {
+                const firstSelected = question.choices.findIndex((choice) => selection.choiceValues.includes(choice.value));
+                if (firstSelected !== -1)
+                    return firstSelected;
+                return selection.customText !== undefined ? customAnswerIndex(question) : 0;
+            }
             if ("customText" in selection)
                 return customAnswerIndex(question);
             const choiceIndex = question.choices.findIndex((choice) => choice.value === selection.choiceValue);
@@ -282,9 +328,18 @@ export async function runQuestionnaire(questions, ctx) {
         function enterCustomMode() {
             const question = currentQuestion();
             const existing = selections.get(question.id);
-            const prefill = existing && "customText" in existing
+            const prefill = existing && "customText" in existing && existing.customText !== undefined
                 ? { text: existing.customText, images: existing.images ?? [] }
                 : customDrafts.get(question.id) ?? { text: "", images: [] };
+            if (question.multiple) {
+                const multi = multipleSelection(question);
+                if (multi.customText === undefined && multi.choiceValues.length >= (question.maxSelections ?? question.choices.length + 1)) {
+                    customError = `Choose at most ${question.maxSelections ?? question.choices.length + 1} answers.`;
+                    refresh();
+                    return;
+                }
+                selections.set(question.id, { ...multi, customText: prefill.text, ...(prefill.images.length > 0 ? { images: prefill.images } : {}) });
+            }
             mode = "custom";
             selectedChoiceIndex = customAnswerIndex(question);
             customError = undefined;
@@ -295,14 +350,43 @@ export async function runQuestionnaire(questions, ctx) {
             const question = currentQuestion();
             const choice = question.choices[index];
             if (choice) {
+                if (question.multiple) {
+                    const existing = multipleSelection(question);
+                    const selected = existing.choiceValues.includes(choice.value);
+                    const selectedCount = existing.choiceValues.length + (existing.customText !== undefined ? 1 : 0);
+                    if (!selected && selectedCount >= (question.maxSelections ?? question.choices.length + 1)) {
+                        customError = `Choose at most ${question.maxSelections ?? question.choices.length + 1} answers.`;
+                        refresh();
+                        return;
+                    }
+                    const choiceValues = selected
+                        ? existing.choiceValues.filter((value) => value !== choice.value)
+                        : question.choices.filter((candidate) => candidate.value === choice.value || existing.choiceValues.includes(candidate.value)).map((candidate) => candidate.value);
+                    selections.set(question.id, { ...existing, choiceValues });
+                    customError = undefined;
+                    refresh();
+                    return;
+                }
                 selections.set(question.id, { id: question.id, choiceValue: choice.value });
                 customDrafts.delete(question.id);
                 clearSharedEditorText();
                 advanceAfterAnswer();
                 return;
             }
-            if (index === question.choices.length)
+            if (index === question.choices.length) {
+                if (question.multiple) {
+                    const existing = multipleSelection(question);
+                    if (existing.customText !== undefined) {
+                        customDrafts.set(question.id, { text: existing.customText, images: existing.images ?? [] });
+                        const { customText: _customText, images: _images, ...withoutCustom } = existing;
+                        selections.set(question.id, withoutCustom);
+                        customError = undefined;
+                        refresh();
+                        return;
+                    }
+                }
                 enterCustomMode();
+            }
         }
         function submitCustomAnswer() {
             const snapshot = sharedEditorSnapshot();
@@ -313,6 +397,22 @@ export async function runQuestionnaire(questions, ctx) {
                 return;
             }
             const question = currentQuestion();
+            if (question.multiple) {
+                const existing = multipleSelection(question);
+                selections.set(question.id, {
+                    id: question.id,
+                    choiceValues: existing.choiceValues,
+                    customText: trimmed,
+                    ...(snapshot.images.length > 0 ? { images: snapshot.images } : {}),
+                });
+                customDrafts.delete(question.id);
+                clearSharedEditorText();
+                mode = "choices";
+                customError = undefined;
+                syncChoiceSelection();
+                refresh();
+                return;
+            }
             selections.set(question.id, {
                 id: question.id,
                 customText: trimmed,
@@ -458,7 +558,7 @@ export async function runQuestionnaire(questions, ctx) {
                 goBack();
                 return;
             }
-            if (isKey(data, "enter")) {
+            if (isKey(data, "enter") || data === " ") {
                 selectChoice(selectedChoiceIndex);
                 return;
             }
@@ -481,7 +581,8 @@ export async function runQuestionnaire(questions, ctx) {
             const zones = [];
             const active = activeTab();
             for (let index = 0; index < questions.length; index += 1) {
-                const answered = selections.has(questions[index].id);
+                const question = questions[index];
+                const answered = selectionIsComplete(question, selections.get(question.id));
                 const label = ` ${index + 1}${answered ? "✓" : "·"} `;
                 const startColumn = visibleLength(plain) + 1;
                 plain += label;
@@ -517,9 +618,10 @@ export async function runQuestionnaire(questions, ctx) {
             renderSeparator(add, width);
             questions.forEach((question, index) => {
                 const answer = selections.get(question.id);
+                const complete = selectionIsComplete(question, answer);
                 const label = answer ? formatReviewAnswerLabel(question, answer) : "Unanswered";
-                const status = answer ? "✓" : "·";
-                renderSelectableLine(add, index === selectedReviewIndex, `${status} ${index + 1}. ${question.label}: ${label}`, { kind: "review", index }, width, answer ? "success" : "warning");
+                const status = complete ? "✓" : "·";
+                renderSelectableLine(add, index === selectedReviewIndex, `${status} ${index + 1}. ${question.label}: ${label}`, { kind: "review", index }, width, complete ? "success" : "warning");
             });
             const isComplete = Boolean(getCompleteSelections());
             renderSeparator(add, width);
@@ -527,16 +629,22 @@ export async function runQuestionnaire(questions, ctx) {
         }
         function renderQuestion(add, addWrapped, width) {
             const question = currentQuestion();
+            const selection = selections.get(question.id);
+            const multiSelection = selection && "choiceValues" in selection ? selection : undefined;
             renderHeader(add, `${questionIndex + 1}/${questions.length} ${question.label}`, width);
             renderTabs(add, width);
             renderSeparator(add, width);
             addWrapped(theme.fg("info", ` ${question.prompt}`));
+            if (question.multiple)
+                addWrapped(theme.fg("muted", ` Select ${question.minSelections ?? 1} to ${question.maxSelections ?? question.choices.length + 1} answers.`));
             question.choices.forEach((choice, index) => {
-                renderSelectableLine(add, mode === "choices" && index === selectedChoiceIndex, `${index + 1}. ${choice.label}`, { kind: "choice", index }, width, "warning");
+                const prefix = question.multiple ? `[${multiSelection?.choiceValues.includes(choice.value) ? "x" : " "}]` : `${index + 1}.`;
+                renderSelectableLine(add, mode === "choices" && index === selectedChoiceIndex, `${prefix} ${choice.label}`, { kind: "choice", index }, width, "warning");
                 if (choice.description)
                     renderMutedLine(add, `    ${choice.description}`, width);
             });
-            renderSelectableLine(add, mode === "choices" && selectedChoiceIndex === customAnswerIndex(), `${question.choices.length + 1}. ${CUSTOM_ANSWER_LABEL}`, { kind: "custom" }, width, "warning");
+            const customPrefix = question.multiple ? `[${multiSelection?.customText !== undefined ? "x" : " "}]` : `${question.choices.length + 1}.`;
+            renderSelectableLine(add, mode === "choices" && selectedChoiceIndex === customAnswerIndex(), `${customPrefix} ${CUSTOM_ANSWER_LABEL}`, { kind: "custom" }, width, "warning");
             if (mode === "custom") {
                 if (!usesSharedEditor) {
                     (sharedEditorText() || " ").split("\n").forEach((line) => addWrapped(theme.fg("text", ` ${line}`)));
@@ -544,6 +652,8 @@ export async function runQuestionnaire(questions, ctx) {
                 if (customError && !sharedEditorText().trim())
                     addWrapped(theme.fg("warning", ` ${customError}`));
             }
+            if (mode === "choices" && customError)
+                addWrapped(theme.fg("warning", ` ${customError}`));
         }
         function handleMouse(event) {
             if (!event.released)
@@ -562,7 +672,12 @@ export async function runQuestionnaire(questions, ctx) {
                     selectChoice(zone.index);
                     return true;
                 case "custom":
-                    enterCustomMode();
+                    if (mode === "custom") {
+                        captureCustomDraft();
+                        mode = "choices";
+                    }
+                    selectedChoiceIndex = customAnswerIndex();
+                    selectChoice(selectedChoiceIndex);
                     return true;
                 case "review":
                     moveToQuestion(zone.index);

package/dist/bundled-extensions/question/types.d.ts

@@ -8,6 +8,9 @@ export interface QuestionInput {
     label: string;
     prompt: string;
     choices: QuestionChoiceInput[];
+    multiple?: boolean;
+    minSelections?: number;
+    maxSelections?: number;
 }
 export interface QuestionToolInput {
     questions: QuestionInput[];
@@ -22,6 +25,9 @@ export interface NormalizedQuestion {
     label: string;
     prompt: string;
     choices: NormalizedQuestionChoice[];
+    multiple?: true;
+    minSelections?: number;
+    maxSelections?: number;
 }
 export interface PredefinedQuestionSelection {
     id: string;
@@ -32,15 +38,29 @@ export interface CustomQuestionSelection {
     customText: string;
     images?: QuestionImageContent[];
 }
-export type QuestionSelection = PredefinedQuestionSelection | CustomQuestionSelection;
-export interface QuestionAnswer {
+export interface MultipleQuestionSelection {
     id: string;
+    choiceValues: string[];
+    customText?: string;
+    images?: QuestionImageContent[];
+}
+export type QuestionSelection = PredefinedQuestionSelection | CustomQuestionSelection | MultipleQuestionSelection;
+export interface QuestionAnswerSelection {
     value: string;
     label: string;
     wasCustom: boolean;
     index?: number;
     imageCount?: number;
 }
+export interface SingleQuestionAnswer extends QuestionAnswerSelection {
+    id: string;
+}
+export interface MultipleQuestionAnswer {
+    id: string;
+    multiple: true;
+    selections: QuestionAnswerSelection[];
+}
+export type QuestionAnswer = SingleQuestionAnswer | MultipleQuestionAnswer;
 export interface SuccessfulQuestionResult {
     answers: QuestionAnswer[];
     canceled: false;
@@ -73,6 +93,7 @@ export interface QuestionUiContext {
     hasUI?: boolean;
     ui: {
         custom<T>(factory: (tui: QuestionTui, theme: QuestionTheme, keybindings: unknown, done: (value: T) => void) => QuestionComponent): Promise<T | undefined>;
+        editor?(title: string, prefill?: string): Promise<string | undefined>;
         setEditorText?(text: string): void;
         getEditorText?(): string;
         setEditorSnapshot?(snapshot: QuestionEditorSnapshot): void;

package/dist/tool-renderers/question.js

@@ -38,6 +38,9 @@ function formatQuestions(questions) {
     return questions.map((question, index) => {
         const title = `◇ ${index + 1}/${questions.length} ${questionLabel(question)}`;
         const prompt = stringValue(question.prompt) ?? "(no prompt)";
+        const bounds = question.multiple === true
+            ? `  Select ${integerValue(question.minSelections) ?? 1} to ${integerValue(question.maxSelections) ?? ((Array.isArray(question.choices) ? question.choices.length : 0) + 1)} answers.`
+            : undefined;
         const choices = Array.isArray(question.choices)
             ? question.choices.filter(isPlainRecord)
             : [];
@@ -47,7 +50,7 @@ function formatQuestions(questions) {
             return description ? `  ${choiceIndex + 1}. ${label} — ${description}` : `  ${choiceIndex + 1}. ${label}`;
         });
         choiceLines.push(`  ${choices.length + 1}. ${CUSTOM_ANSWER_LABEL} (custom answer)`);
-        return [title, `  ${prompt}`, ...choiceLines].join("\n");
+        return [title, `  ${prompt}`, ...(bounds ? [bounds] : []), ...choiceLines].join("\n");
     }).join("\n\n");
 }
 function formatQuestionResult(details, questions) {
@@ -71,18 +74,34 @@ function formatQuestionResult(details, questions) {
 }
 function formatAnswer(answer, questionLabels) {
     const label = questionLabels.get(stringValue(answer.id)) ?? stringValue(answer.id) ?? "Question";
+    if (answer.multiple === true && Array.isArray(answer.selections)) {
+        const selections = answer.selections.filter(isPlainRecord).map((selection) => formatAnswerSelection(selection));
+        return `✓ ${label}: ${selections.join(", ") || "(empty)"}`;
+    }
     const answerLabel = stringValue(answer.label) ?? "(empty)";
     if (answer.wasCustom === true)
         return `✓ ${label}: ${answerLabel} (custom answer)`;
     const index = typeof answer.index === "number" && Number.isFinite(answer.index) ? `choice ${answer.index}` : "choice";
     return `✓ ${label}: ${answerLabel} (${index})`;
 }
+function formatAnswerSelection(answer) {
+    const label = stringValue(answer.label) ?? "(empty)";
+    if (answer.wasCustom === true) {
+        const imageCount = integerValue(answer.imageCount);
+        return `${label} (custom answer${imageCount ? `; ${imageCount} image${imageCount === 1 ? "" : "s"} attached` : ""})`;
+    }
+    const index = integerValue(answer.index);
+    return `${label} (${index === undefined ? "choice" : `choice ${index}`})`;
+}
 function questionLabel(question) {
     return stringValue(question.label) ?? stringValue(question.id) ?? "Question";
 }
 function stringValue(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+function integerValue(value) {
+    return typeof value === "number" && Number.isInteger(value) ? value : undefined;
+}
 function isPlainRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/docs/desktop-markdown-media.md

@@ -0,0 +1,77 @@
+# Spec: Desktop Markdown media previews
+
+## Type
+
+Change
+
+## Goal
+
+Show an inline preview when transcript Markdown links to a supported local image or video, including `file://` artifacts outside the active workspace, and keep every local artifact label actionable.
+
+## Scope
+
+- Relative Markdown destinations that resolve inside the active workspace.
+- Absolute local paths expressed as `file://` Markdown destinations, such as QA artifacts in the system temporary directory.
+- Image formats: AVIF, BMP, GIF, JPEG, PNG, SVG, and WebP.
+- Video formats: M4V, MOV, MP4, OGV, and WebM.
+- Both ordinary Markdown links and local Markdown image syntax.
+
+## Non-goals
+
+- Embedding remote media.
+- Adding codecs beyond those supported by the desktop WebView.
+- Changing previews for non-media project files.
+- Inline previews for non-media `file://` artifacts; those remain links and open in the operating-system default application.
+
+## Behavior
+
+- A supported local media link renders an inline, bounded preview with its Markdown label as a caption.
+- A supported `file://` media link uses the same preview treatment after its URL is decoded to an absolute local path.
+- Images are lazy-loaded and open the existing media preview dialog when clicked.
+- Videos expose native inline playback controls; their caption opens the media preview dialog.
+- A missing, disallowed, or unrenderable media file leaves a readable fallback and a clickable caption.
+- Opening a supported media link uses the media path flow, not the UTF-8 source-file reader.
+- Other relative project links continue to open the source preview dialog.
+- Other `file://` links remain visibly clickable and open only after an explicit click.
+
+## Contracts
+
+- The frontend requests a resolved media file using the active workspace and normalized relative path.
+- The backend canonicalizes both workspace and destination, rejects traversal and symlink escapes, verifies a supported extension, and grants asset-protocol access only to the resolved file.
+- A `file://` destination is accepted only when it decodes to an absolute path. The backend canonicalizes it, requires an existing regular file, and grants asset-protocol access only for supported image/video previews.
+- Non-media local files are passed to the OS opener only in response to a user click.
+- Markdown output continues to escape labels, paths, and attributes before insertion through `{@html}`.
+
+## Edge cases
+
+- URL-like, absolute, control-character, and parent-traversing destinations are not treated as project media.
+- URL schemes other than `file://`, malformed file URLs, relative `file:` forms, and decoded control characters are not treated as local files.
+- Query strings and fragments are removed by the existing project-path normalization.
+- Media loading failures do not replace the transcript with a global error.
+- Clicking a failed media caption still reports the underlying file-resolution error through the normal project-file action.
+
+## Related files
+
+- `desktop/src/lib/markdown.ts`
+- `desktop/src/components/MarkdownText.svelte`
+- `desktop/src/App.svelte`
+- `desktop/src-tauri/src/lib.rs`
+
+## Verification
+
+- Markdown unit tests cover workspace and `file://` image/video links, image syntax, escaping, and rejected destinations.
+- Rust unit tests cover supported workspace/absolute media, unsupported binary files, relative local paths, traversal, and workspace containment.
+- `npm run test`, `npm run check`, and `npm run build:web` pass in `desktop/`.
+- `cargo test` passes in `desktop/src-tauri/`.
+
+## Risks / unknowns
+
+- Actual video playback remains codec-dependent in the operating-system WebView; load failures use the fallback state.
+- A transcript can request an inline view of any readable local image/video via an explicit `file://` URL. The bytes remain local and are exposed only to the app's scoped asset protocol.
+
+## Evidence
+
+- Confirmed by code: relative links currently call `read_project_file`, which always decodes bytes as UTF-8.
+- Confirmed by code: attachment previews already use Tauri's scoped asset protocol and the existing media dialog.
+- Confirmed by the reported session: QA artifact links use `file:///tmp/...`, which the project-path normalizer intentionally rejects and previously reduced to plain labels.
+- Confirmed by tests: project paths are normalized and constrained to the active workspace.

package/docs/desktop-mvp.md

@@ -0,0 +1,134 @@
+# Spec: Pix Desktop MVP
+
+## Type
+
+Change
+
+## Goal
+
+Provide a lightweight desktop client for Pix using Tauri 2 and Svelte 5 +
+TypeScript. The first vertical slice must let a user select a workspace, open
+or create a pi session, send a prompt, observe streamed assistant/thought/tool
+updates, cancel a running turn, and answer extension elicitations.
+
+## Scope
+
+- A standalone `desktop/` package; the existing terminal UI remains unchanged.
+- A Tauri process host for the existing `acp/dist/main.js` adapter.
+- An ACP 1.4 JSON-RPC client in the Svelte application.
+- Workspace selection, recent sessions, transcript replay, model/thinking
+  selectors, prompt composition, cancellation, and one-field form
+  elicitations.
+- Development commands and a documented local setup path.
+
+## Non-goals
+
+- Feature parity with `PiUiExtendApp`.
+- Voice input, an embedded terminal, custom widgets, image attachments,
+  markdown/diff rendering, or authentication management.
+- Bundling Node or a platform-specific standalone `pix-acp` executable in this
+  first slice. Development uses Node plus pix-acp's pinned pi npm dependency;
+  distributable sidecar packaging is a follow-up milestone.
+- Reimplementing the pi runtime in Rust or the webview.
+
+## Behavior
+
+1. Tauri starts one isolated `pix-acp` child and exposes only start, line-send,
+   and stop commands to the webview. Arbitrary shell execution is not exposed.
+2. The client initializes ACP with form-elicitation support before creating or
+   loading a session.
+3. Selecting a workspace lists its persisted sessions. The user can create a
+   session or load one; loading replays its transcript. Clicking the active
+   session tab opens a searchable session selector below the tabs, matching the
+   terminal UI's active-tab behavior. Each visible tab also has a close button;
+   closing a tab does not delete its persisted session, so it remains available
+   from the selector.
+4. A submitted prompt appears immediately as a user message. ACP
+   `session/update` notifications incrementally update assistant text,
+   thoughts, and tool activity.
+5. While a prompt request is pending, duplicate submission is disabled and a
+   stop action sends `session/cancel`. Final updates remain accepted until the
+   prompt response settles.
+6. Model and thought-level controls reflect ACP `configOptions` and use
+   `session/set_config_option` for changes.
+7. A form `elicitation/create` request blocks in a modal until the user accepts
+   or cancels. String/select/boolean fields emitted by `pix-acp` are supported.
+8. Adapter exits, malformed protocol messages, and request failures are shown
+   as recoverable UI errors; all pending requests reject when the adapter exits.
+
+## Contracts
+
+- Webview → Rust commands:
+  - `acp_start()` returning the child generation number
+  - `acp_send(generation, line)` where `line` is one newline-free JSON-RPC
+    object and the generation must still own the child
+  - `acp_stop(generation)`; stale generations cannot stop a replacement child
+- Rust → webview events:
+  - `acp://stdout` with `{ generation, line }` for one complete stdout line
+  - `acp://stderr` with `{ generation, line }` for one diagnostic line
+  - `acp://exit` with the generation and child exit status
+- Rust starts `node ../../acp/dist/main.js` by default. `PIX_ACP_NODE_BINARY`
+  and `PIX_ACP_ENTRY` may override executable and entry path for development.
+- Webview ↔ adapter payloads follow `@agentclientprotocol/sdk` 1.4.0 types.
+
+## Invariants
+
+- ACP stdout is protocol-only; diagnostics are never parsed as JSON-RPC.
+- At most one adapter child is owned by an application window.
+- At most one active prompt exists per ACP session.
+- A workspace path must be non-empty and absolute before `session/new` or
+  `session/load`.
+- Pending JSON-RPC calls have deterministic cleanup on response, send failure,
+  adapter exit, and client disposal.
+- Reconnect clears session-local UI state and ignores events from older child
+  generations.
+
+## Edge cases
+
+- Repeated start is idempotent; repeated stop succeeds.
+- Stop closes adapter stdin first so pix-acp can dispose nested pi processes,
+  then forces termination after a bounded grace period.
+- A stale persisted session may fail to load; the UI remains usable for a new
+  session.
+- Cancellation is a notification, so the UI waits for the original prompt
+  response rather than assuming immediate completion.
+- Unknown ACP updates are ignored rather than crashing the transcript.
+- Unsupported or malformed elicitation schemas are cancelled.
+
+## Related files
+
+- `desktop/`
+- `acp/src/main.ts`
+- `acp/src/acp/pix-acp-agent.ts`
+- `acp/src/acp/event-translator.ts`
+- `acp/src/acp/ui-request-bridge.ts`
+
+## Verification
+
+- `npm --prefix desktop run check`
+- `npm --prefix desktop test`
+- `npm run check:acp`
+- `npm run check`
+- `cargo check --manifest-path desktop/src-tauri/Cargo.toml`
+
+## Risks / unknowns
+
+- Production bundles still need a platform-specific strategy for shipping
+  Node/pi/pix-acp or a compiled standalone sidecar.
+- Tauri/Rust verification requires a local Rust toolchain; frontend tests
+  remain runnable independently.
+- ACP 1.4 live message chunks from `pix-acp` may omit `messageId`; the desktop
+  reducer therefore coalesces adjacent chunks by role when no id is present.
+
+## Evidence
+
+- Confirmed by code: `pix-acp` supports the required session, prompt, cancel,
+  config, streamed update, replay, and elicitation surfaces.
+- Confirmed by tests: `acp/test/agent.test.ts` and
+  `acp/test/event-translator.test.ts` cover those adapter contracts.
+- Confirmed by docs: Tauri 2 supports a Vite frontend and child-process event
+  bridging; Svelte 5 supports typed components and rune-based state.
+- Inferred: a narrow Rust process host is safer and easier to package later
+  than exposing a general shell plugin to the webview.
+- Unknown: final production sidecar packaging format and signing/notarization
+  workflow.