Skip to content

docs(app-kit): show stable ChatEmbed file and artifact handlers (#20220) - #20662

Merged
buluoray merged 1 commit into
mainfrom
fix/chatembed-stable-callbacks-docs-20220
Oct 15, 2026
Merged

buluoray merged 1 commit into
mainfrom
fix/chatembed-stable-callbacks-docs-20220

Conversation

@buluoray

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: App authors who copy the Embedded Chat example get file and artifact handlers that do not re-render the transcript on every host render.

The Embedded Chat example in docs/app-kit/api-reference.md passed inline arrows to onFileOpen and onArtifactOpen. ChatMessageList lists both callbacks in the dependency array of its memoized renderMessage (useCallback, website/src/app-sdk/ChatMessageList.tsx:305), and ChatEmbed hands them straight through, so a new function identity on each host render throws that memo away and every message re-renders.

Why it matters

The example is the template app authors copy. Copied as written, every embedded chat re-renders its whole transcript whenever the host component renders, which gets slower as the conversation grows.

Not a goal

  • No change to ChatEmbed, ChatMessageList or any callback signature.
  • No runtime guard against unstable callbacks.

What changed (motivation → approach → change)

Inline arrows in the documented example → new identities each render invalidate renderMessage → the example now shows both stable forms the issue allows:

  • onFileOpen wrapped in useCallback with its one dependency (viewer), using the documented (path, opts?: { line?, endLine? }) shape.
  • onArtifactOpen as a function defined outside the component.

One short paragraph above the example says why: keep both handlers the same function between renders while their behaviour does not change, since the transcript re-renders whenever either changes identity. The paragraph describing the signatures and the omitted-prop behaviour is unchanged.

Backwards compatibility

Compatible: documentation only; no code, type or signature changes.

Removes nothing: the diff only rewrites a docs example and adds one paragraph.

Tests

N/A — documentation-only change. python3 scripts/docs_lint.py and ./scripts/docs-lint.sh pass locally, and neither reports a new identifier hit for the example's names.

Manual verification

Checked the example's onFileOpen parameter shape against ChatEmbedProps.onFileOpen in website/src/app-sdk/ChatEmbed.tsx:125 and the memo dependency list in ChatMessageList.tsx:305 on this branch's base.

Related Issues

Closes #20220

Follow-up to the review on #19889. Open #19879 edits the same file but does not touch this example or these callbacks.

Decision for the owner

The decision is how the docs should show stable onFileOpen and onArtifactOpen handlers for ChatEmbed. This draft shows useCallback for the handler that reads component state and a module-level function for the one that does not, so readers see both forms the issue names without a useCallback around a function that never changes.

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.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 60f37d7a31245053ff42a8d4b04f16780ef3bf5f ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 60f37d7a31245053ff42a8d4b04f16780ef3bf5f touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 60f37d7a31245053ff42a8d4b04f16780ef3bf5f — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 60f37d7

Description read

[DESCRIPTION-READ] fea33a012faf2cb3748c010621729e16cfc7c4867c5ff686029dba408d79e553

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 60f37d7a31245053ff42a8d4b04f16780ef3bf5f — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 60f37d7

Verdict parsed from the review's SHA-scoped output markers for commit 60f37d7a31245053ff42a8d4b04f16780ef3bf5f.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 60f37d7a31245053ff42a8d4b04f16780ef3bf5f: <one-sentence reason>

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 60f37d7a31245053ff42a8d4b04f16780ef3bf5f and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 60f37d7

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 60f37d7a31245053ff42a8d4b04f16780ef3bf5f: <one-sentence reason>

@buluoray
buluoray marked this pull request as ready for review October 15, 2026 09:07
@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners October 15, 2026 09:07
@buluoray
buluoray requested a review from mbriones98 October 15, 2026 09:07
@buluoray
buluoray enabled auto-merge (squash) October 15, 2026 09:07
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 15, 2026

@mbriones98 mbriones98 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.

Checks green and readiness passed at 60f37d7; no behavior change.

@buluoray
buluoray merged commit a1c4892 into main Oct 15, 2026
103 checks passed
@buluoray
buluoray deleted the fix/chatembed-stable-callbacks-docs-20220 branch October 15, 2026 09:11
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document stable ChatEmbed file and artifact callbacks

2 participants