Skip to content

feat(app-sdk): let ChatEmbed take a renderers prop and pass it to its transcript - #29850

Merged
bolichen97 merged 1 commit into
mainfrom
feat/chatembed-renderers
Nov 4, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/chatembed-renderers

Conversation

@buluoray

@buluoray buluoray commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An app embedding ChatEmbed can restyle its transcript rows (for example, an agent avatar beside replies, or replies in bubbles) by passing renderers, without rebuilding the composer, Stop, queue, approvals and follow-up chips.

ChatMessageList already takes renderers?: readonly MessageRenderer[] and merges them over the built-in registry, and the SDK exports MessageRenderer, MessageRenderContext, mergeRenderers and defaultMessageRenderers. ChatEmbed mounts its own ChatMessageList but neither accepts nor forwards renderers, so a host that wants a different row look today has to drop ChatEmbed and re-implement everything around a bare ChatMessageList.

Why it matters

Hosts that only want a different message look are pushed into copying the embed's composer, Stop, queue, approval and follow-up logic, which then drifts from the shared implementation.

Not a goal

What changed (motivation → approach → change)

Gap: the embed drops the list's existing extension point. Approach: pass the prop straight through, with the list's own semantics, rather than adding an embed-specific styling API. Change:

  • website/src/app-sdk/ChatEmbed.tsx: ChatEmbedProps.renderers?: readonly MessageRenderer[], documented (merged over the built-ins; presentation only, removing parts stays hide; pass a stable array because the list memoizes mergeRenderers on its identity), forwarded to the embed's ChatMessageList.
  • docs/app-kit/api-reference.md: prop table row and a "Restyling rows" subsection: the merge order, the two ways an entry takes over more than intended (reusing a built-in id drops every role it drew, including streaming; a role claim without match takes the compaction notice), and a stable-array example that claims exactly the built-in assistant rows and wraps their render.
  • docs/system-specs/modules/app-kit-platform.md: "Embedded chat renderers" section with the same contract.

Backwards compatibility

Compatible: the prop is optional, and when it is omitted ChatMessageList receives undefined, exactly as before.

Removes nothing: the diff only adds an optional prop and its pass-through.

Tests

  • website/src/test/ChatEmbed.renderers.test.tsx mounts the real ChatEmbed and ChatMessageList with the documented restyling entry (claims what resolveRenderer(m, defaultMessageRenderers) gives the built-in assistant entry, wraps its render): the settled reply and the live streaming tail draw through the host wrapper, while the user row and a compaction notice keep their built-in rows; with no renderers the built-in reply row renders.
  • Mutation: deleting the literal line renderers={renderers} from the ChatMessageList mount turns the two host-entry tests red; restored, they pass.
  • The naive entry (id: 'assistant', roles: ['assistant'], no match) also turns both host-entry tests red, so the test pins the pitfall the docs warn about.

Proof: not provable -- frontend test (prove.py runs Python only)

Ran locally: npx vitest run src/test/ChatEmbed src/test/ChatMessageList src/test/messageRenderers (31 files, 396 tests passed), npx tsc -p tsconfig.app.json, npx eslint on the changed files, ./scripts/docs-lint.sh, python3 scripts/docs_lint.py --test, and the backend tests that reference the changed docs (285 passed, 1 skipped).

Manual verification

N/A — unit coverage sufficient: the change is a prop pass-through and the test renders the real list and registry.

Screenshots / video

Why no screenshot: Without the new optional prop the embed renders exactly as before; the only visual change is whatever a host's own renderer draws.

Related Issues

Closes #29848

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 4, 2026 18:17
@buluoray
buluoray requested a review from CrysisDeu November 4, 2026 18:17
@buluoray buluoray added area: apps App Store, app-sdk, MCP apps, app runtime enhancement New feature or request labels Nov 4, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 4, 2026
@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 2ecd7baa3a3c3ed1083cc3040ea2841576a9069b — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing to check. The diff adds an optional developer prop that is passed straight through, and no rendered control changes. When a host omits renderers, the embed looks exactly as it did before, so there is nothing that needs a screenshot.

[UX-REVIEWED] 2ecd7ba

Description read

[DESCRIPTION-READ] e3e9ba977be8fd2c2fe41b643036e5b1c2fe0ef105721f10e563c0c431b1830c

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 2ecd7baa3a3c3ed1083cc3040ea2841576a9069b — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. This is an optional pass-through of the list's existing extension point, and the embed renders nothing new by default.

[DESIGN-REVIEWED] 2ecd7ba

Description read

[DESCRIPTION-READ] 49d8d7a9dfa2dac08a591e2d94afdae8ddc83d9fcb74e50e71820aeac27c8347

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 2ecd7baa3a3c3ed1083cc3040ea2841576a9069b — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks: this is a one-line pass-through to an extension point ChatMessageList already has. External apps are the intended consumers under the no-built-in-apps rule, and #29848 asks for it.

Notes

  • Item 3 — oversized: the ChatEmbedProps.renderers JSDoc repeats, at 14 lines, the merge order and both pitfalls that api-reference.md "Restyling rows" and the spec section already state. That makes three copies of one contract to keep in sync. Subtraction: cut the JSDoc to one sentence ("Handed to ChatMessageList; pass a stable array; see docs/app-kit/api-reference.md, 'Restyling rows'.") and drop the restated merge and pitfall text.

What this change ships

Inventory (4 items) — 3 justified

Intent: let an app restyle ChatEmbed's transcript rows without re-building the composer and controls around a bare ChatMessageList. This is an ADDITION.

  1. ChatEmbed accepts an optional renderers prop and passes it to its transcript list — justified
  2. The app-kit API reference gains a prop row and a "Restyling rows" example — justified
  3. The prop's JSDoc restates the merge order and the pitfalls — oversized
  4. The app-kit-platform spec gains an "Embedded chat renderers" section — justified

[FIRST-PRINCIPLES-REVIEWED] 2ecd7ba

Description read

[DESCRIPTION-READ] 0407facff77f8e8eedb9dfd81a0ccb2a75c9cf87634d867d7febafb5076d5413

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 2ecd7baa3a3c3ed1083cc3040ea2841576a9069b — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 2ecd7ba

Verdict parsed from the review's SHA-scoped output markers for commit 2ecd7baa3a3c3ed1083cc3040ea2841576a9069b.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 2ecd7baa3a3c3ed1083cc3040ea2841576a9069b false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 2ecd7baa3a3c3ed1083cc3040ea2841576a9069b and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2ecd7ba

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 2ecd7baa3a3c3ed1083cc3040ea2841576a9069b false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 4, 2026
… transcript

ChatMessageList already merges host renderers over the built-in registry,
but ChatEmbed mounted its own list without forwarding them, so a host that
wanted a different row look had to rebuild the composer, Stop, queue and
approvals around a bare ChatMessageList.

Closes #29848
@buluoray
buluoray force-pushed the feat/chatembed-renderers branch from f2732ee to 2ecd7ba Compare November 4, 2026 18:39
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 4, 2026
@buluoray

buluoray commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Kiro Crew Auto-Pipeline [operator: buluoray#29848]:

Opus 5.5 BLOCKING finding on f2732eef5c (the documented renderers example hides the streaming tail and swallows the compaction notice): confirmed and fixed in 2ecd7baa3a.

  • Verified in source: mergeRenderers drops a reused built-in id with all its roles (the built-in assistant entry draws ['assistant', 'streaming']), and host entries sit ahead of the role-keyed system_notice entry, so a match-less assistant claim takes it.
  • The docs example, the spec section and the ChatEmbedProps.renderers JSDoc now use a fresh id that claims exactly what resolveRenderer(m, defaultMessageRenderers) gives the built-in assistant entry and wraps that entry's render. The docs spell out both pitfalls and the merge order (kind-matched built-ins, then host entries, then role-keyed built-ins), which also fixes the "searched before the built-ins" note.
  • ChatEmbed.renderers.test.tsx now covers the settled reply, the live streaming tail and a compaction notice. The naive entry from the old example (id: 'assistant', roles: ['assistant']) turns both host-entry tests red; removing the renderers={renderers} forwarding line does too.

GPT 6.1's downgraded finding is about cron_turn.py, which this PR does not touch.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 4, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[operator: bolichen97] Approving at head 2ecd7ba.

renderers is optional and forwarded to the existing ChatMessageList prop; when omitted the list receives undefined, exactly as today. No blocking issues.

Non-blocking: the JSDoc on ChatEmbedProps.renderers is long and wraps oddly; it could point to the API reference instead. A host replacing the built-in assistant renderer also drops the streaming row, which is documented; a dev-mode warning would help.

AI-assisted, approved by bolichen97

@bolichen97
bolichen97 merged commit 5d0bd7e into main Nov 4, 2026
151 of 154 checks passed
@bolichen97
bolichen97 deleted the feat/chatembed-renderers branch November 4, 2026 20:39
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: apps App Store, app-sdk, MCP apps, app runtime enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

app-sdk: let ChatEmbed take a renderers prop and pass it to its transcript

2 participants