jetbrains-session

JetBrains Session Component

Detailed reference for the chat session feature in packages/kilo-jetbrains/. See packages/kilo-jetbrains/AGENTS.md for the component-model summary and reuse index; this skill covers the full architecture, background/lifecycle rules, and testing helpers.

Session UI Background Strategy

The chat session UI intentionally uses a single-backdrop model. Do not make every container paint SessionUiStyle.Colors.sessionBackground() just because it sits inside the session. This avoids fragile component-hierarchy coupling and prevents theme-specific artifacts in transparent/rounded Swing painting.

• SessionRootPanel is the primary opaque backdrop. It overrides getBackground() and returns SessionUiStyle.Colors.sessionBackground().
• sessionBackground() follows the panel background, but when that equals the raised editor surface (codeBlockBackground()) — e.g. Islands Dark/Darcula, where panel and editor backgrounds are identical — it shifts by SESSION_DELTA via UiStyle.Colors.contrast (lighter in dark themes, darker in light) so the prompt bubble/input and other raised surfaces stay visible. This is a universal fallback, not a per-theme override.
• SessionRootPanel.Blocker is the only other session-background opaque panel. It also overrides getBackground() with sessionBackground() for modal blocking.
• Scroll panes, viewports, transcript layout panels, message lists, turn containers, wrapper panels, and card bodies should be non-opaque unless they intentionally paint a distinct surface.
• applyStyle(style) must not assign session-background colors. It may update fonts, foregrounds, editor colors, and other non-background styling. Background colors that must be dynamic should come from getBackground() or custom painting.
• Transcript card header hover is getBackground()-driven: keep an isHovered flag on the hover row/header, set or clear it from mouse enter/exit, and repaint only that row/header. Do not assign row.background or header.background on hover.
• Primary/secondary transcript card bodies are transparent by default. The actual content inside a body (code blocks, todo list, shell/tool output) is the raised surface: make that content component opaque and paint SessionUiStyle.Colors.codeBlockBackground() (the editor background), using its own insets so the fill covers the whole content. For MdView-backed bodies set md.opaque = false so the prose/body stays transparent while the code/output panes remain the opaque editor surface — do not make the whole body opaque.
• Rounded cards that paint their own surface (for example RoundedContentPanel-based question/login cards) should do that in custom painting or a contentColor() override, not by making every nested panel opaque.
• Standard platform buttons placed on custom-painted session cards should not force the card background. If a button sits on a rounded/custom-painted card, make it non-opaque when needed so Swing does not fill its rectangular bounds behind DarculaButtonUI's rounded paint (notably visible in Islands Light).
• DialogView (question, permission, login-required, outcome, revert, onboarding cards) is a fourth documented surface: contentColor() paints SessionUiStyle.View.Dialog.bgColor() — a DIALOG_DELTA contrast shift off the backdrop — while outlined is true, so the card reads as its own panel, distinct from both the backdrop and codeBlockBackground(). Its border is Dialog.outlineColor(), the midpoint between backdrop and card fill, so the edge is a soft transition rather than the hard Outline.brightColor() line a fill-less card needs. setOutlined(false) drops back to the plain backdrop color with no outline, for chrome-free states like an interrupted-run note.