<!-- 04_VISUAL/xwui/xwui-lib/xwui-lib-super/src/collaboration/XWUIProposalPanel/XWUIProposalPanel.md -->
# XWUIProposalPanel

The one suggest-only AI surface: a proposal moving through think, stream and ready; the streamed narrative and numbered findings (each with a why line and evidence chips), the proposed changes (add, change, remove, move, plus `same` context rows) with before and after values, optional include boxes and locked rows with their reason, impact rows with delta chips, and one Accept with Discard, Stop, Regenerate, Undo and Retry. It never writes anything: every command is an event and the HOST moves the phase (GUIDE_16, autonomy `suggest`). It composes XWUITextStream (the streamed text), XWUIButton, XWUIInputCheckbox, XWUIStopGenerationButton, XWUITag, XWUIChip and XWUIProgressSkeleton, and reads the shared agent proposal type `XWUISuperProposal` through `proposalFromSuperProposal()`.

## Basic Usage

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: Board assistant draft: six proposed items, five included, Accept 5 items, applied and Undo.
```

## Schedule check

```example
file: examples/ScheduleCheck.ts
html: examples/ScheduleCheck.html
title: Schedule check
description: Streamed findings with a caret, then a fix with impact, why and evidence.
```

## Phases

| Phase | Draws | Commands |
| --- | --- | --- |
| `idle` | title, mode pill, brief | Run (`regenerate` event, label `labels.run`) |
| `thinking` | typing dots, `labels.thinking`, skeleton lines | Stop (also Escape) |
| `streaming` | narrative, then findings, revealed by `revealed` words with one caret | Stop (also Escape) |
| `ready` | findings, changes, impact, why, evidence, note; "nothing to suggest" when empty | Accept (disabled with its reason when nothing is included), Discard, Regenerate |
| `applying` | as ready, Accept busy, boxes disabled | none |
| `applied` | applied strip (`appliedNote` or `labels.applied`) | Undo |
| `discarded` | findings and `labels.discarded` | Regenerate |
| `error` | `error` text | Retry |
| `stale` | changes read-only and `labels.stale` | Regenerate, Discard |

List mode: `proposals[]` draws one entry per proposal, each with its own phase, changes and commit; the panel's own row offers only Regenerate. `layout: 'compact'` is a read-only HUD (title, narrative, changes with struck old values; no boxes, no commands).

## Data

| Field | Meaning |
| --- | --- |
| `phase` | `idle` (default), `thinking`, `streaming`, `ready`, `applying`, `applied`, `discarded`, `error`, `stale` |
| `title`, `prompt` | heading and the brief the proposal answers |
| `text`, `revealed` | streamed narrative; `revealed` words spread over `text` then each finding's text (host pacing) |
| `findings[]` | `{ id, title, text, why?, evidence? }` |
| `items[]` | `{ id, kind, label, sub?, before?, after?, meta?, reason?, included?, locked?: { reason }, evidence? }` |
| `impact[]` | `{ label, before?, after, delta?: { text, tone: ok, warn, bad, neutral } }` |
| `evidence[]` | `{ id, label, key?, href?, targetId?, source? }`; an href that is not http(s), mailto, hash or a path is dropped |
| `why`, `note`, `error`, `appliedNote`, `sampleData` | the why line, a footnote, the error text, the applied strip text, a "Sample data" tag |
| `id`, `proposals[]` | list mode |

## Options

| Option | Default | What it does |
| --- | --- | --- |
| `layout` | `'card'` | `card` (AI ring), `panel` (fills a side sheet, sticky action row), `compact` (read-only HUD) |
| `selection` | `'none'` | `per-item` draws an include box named "Include: label" on every actionable change |
| `commit` | `'selected'` | `selected` commits the included changes, `all` every actionable change |
| `actions` | all six | the commands offered |
| `modeLabel` | none | the autonomy pill |
| `labels` | locale pack | every word; `accept` and `applied` take `{n}`, `selectedCount` takes `{n}` and `{total}`, `include` takes `{label}` |
| `skeletonLines` | `3` | skeleton lines while thinking |
| `valueDir` | `'ltr'` | before and after values in left-to-right isolates, or `auto` for values in words |
| `numberingSystem`, `locale` | `'latn'`, page language | digits of counts |
| `ariaLabel`, `headingLevel` | the title, `2` | region name and title level (sub-headings one lower) |

## Events and methods

Events (each carries `proposalId`: null for the panel, the id of a listed proposal): `onAccept(includedIds, proposalId)`, `onDiscard`, `onStop`, `onRegenerate` (also the idle Run), `onUndo`, `onRetry`, `onIncludeChange({ id, included, includedIds })`, `onEvidenceActivate({ id, href?, targetId? })`. A command is sent once per phase: a double press cannot accept twice.

Methods: `setPhase(phase)`, `setRevealed(words)`, `accept()`, `discard()`, `stop()`, `regenerate()`, `undo()`, `retry()`, `setIncluded(id, included)`, `getIncludedIds()`, `updateData(patch)`, `setData(data)`, `updateConfig(patch)`, `getElement()`, `destroy()`. The fifth constructor argument is the media-query seam (`XWUIPlaybackEnvironment` from `_shared/playback`).

## Accessibility

- A region named by its title; one polite live region that speaks on phase changes and the final count only ("6 changes proposed", "Applied: 5 changes"), never per word. The streamed text is XWUITextStream's projection: the whole text is in the DOM, pending words have no ink.
- Include toggles are real checkboxes named "Include: label". Accept names the count; when nothing is included it is disabled and `aria-describedby` points at the visible reason.
- After Accept focus moves to Undo once the host shows it; after Undo it returns to Accept. Escape stops a proposal that is thinking or streaming.
- Struck values are `<del>` with a hidden "was" prefix; new values are `<ins>`; values sit in direction isolates, identifiers (evidence keys) in left-to-right isolates; tag words take their own direction.
- Evidence chips are focusable buttons (Enter, Space, click). Never colour alone: kind tags in words, struck values, checked boxes, delta text.

## RTL, mobile, motion

Logical properties only; the before/after arrow turns with the writing direction. Below a container width of 24rem the values stack and the action row sticks to the bottom; in `panel` layout it always sticks. Targets grow to `--xwui-size-lg` on coarse pointers. Under `prefers-reduced-motion` (read in JS and CSS) streamed text shows at once with no caret, the orb, dots and entry animations stop.

## Locale keys

`xwui.proposal_panel.*`: `title`, `accept` (plural), `accept_plain`, `discard`, `stop`, `regenerate`, `undo`, `retry`, `run`, `selected_count`, `thinking`, `applied` (plural), `ready` (plural), `locked`, `was`, `none_selected`, `discarded`, `stale`, `empty`, `why`, `evidence`, `impact`, `findings`, `changes`, `include`, `sample`, `kind_add`, `kind_change`, `kind_remove`, `kind_move`, `kind_same`. English fallbacks are built in.

```api
```