# RichUI Interaction API

> Discovered: 2026-03-16

## Context
This applies to RichUI HTML embeds generated by `plugins/pipes/github-copilot-sdk/github_copilot_sdk.py` when the page needs to talk back to the OpenWebUI chat UI.

## Finding
The most reliable design is a small recommended interaction surface with only four primary actions:

1. continue chat now
2. prefill chat input without sending
3. submit the current chat input
4. open an external link

Keeping the recommended API this small reduces LLM choice overload and makes multilingual HTML generation more consistent.

Advanced capabilities still exist, but they are intentionally treated as opt-in patterns rather than the default contract:

- copy text to clipboard
- structured selection state
- template-based prompt/copy actions driven by current selections

## Solution / Pattern
Prefer declarative attributes first:

```html
<!-- 1. Continue chat immediately -->
<button data-openwebui-prompt="Explain this workflow step by step">Explain</button>

<!-- 2. Prefill the chat input only -->
<button
  data-openwebui-prompt="Draft a rollout checklist for this design"
  data-openwebui-action="fill"
>
  Draft in input
</button>

<!-- 3. Submit the current chat input -->
<button data-openwebui-action="submit">Send current draft</button>

<!-- 4. Open a real URL -->
<a data-openwebui-link="https://docs.example.com">Docs</a>
```

When JavaScript is genuinely needed, prefer the object methods:

```javascript
window.OpenWebUIBridge.prompt(text);
window.OpenWebUIBridge.fill(text);
window.OpenWebUIBridge.submit();
window.OpenWebUIBridge.openLink(url);
window.OpenWebUIBridge.reportHeight();
```

Use advanced patterns only when the page genuinely needs them:

```html
<!-- Copy -->
<button data-openwebui-copy="npm run build && npm test">Copy command</button>

<!-- Pick a structured selection -->
<button data-openwebui-select="role" data-openwebui-value="reviewer">
  Reviewer
</button>

<!-- Use the current selection in a follow-up action -->
<button data-openwebui-prompt-template="Explain the responsibilities of {{role}}">
  Explain selected role
</button>
```

### Quick decision guide

- Need an immediate answer now → `data-openwebui-prompt`
- Need the user to review/edit first → `data-openwebui-action="fill"`
- Need to send what is already in chat input → `data-openwebui-action="submit"`
- Need to open an external resource → `data-openwebui-link`
- Need copy UX → `data-openwebui-copy`
- Need pick-then-act UX → `data-openwebui-select` + template placeholder

For most pages, keep to one dominant interaction style and only 2-4 visible actions.

## Gotchas
Inline `onclick` owns click behavior by default. If an element mixes inline click code with declarative prompt/link attributes, declarative handling is skipped unless `data-openwebui-force-declarative="1"` is present.

Legacy aliases such as `sendPrompt(...)` still work for compatibility, but new generated pages should prefer the smaller object-method API or the declarative contract above.

The bridge still keeps a short same-prompt dedupe window as a safety net, but the preferred design is to avoid mixed ownership in the first place.