A read-only block for multi-line source code, configuration, or structured data that must preserve whitespace and remain selectable. Inline Code names one identifier inside prose; CodeBlock presents a complete expression or file excerpt on its own line. The host owns filenames, language labels, actions, loading, and errors.
Authored whitespace is content. Long lines scroll horizontally instead of wrapping, while the host owns vertical measure so a source browser does not create a nested vertical scrollbar inside its Sheet.
{
"component": "CodeBlock",
"purpose": "Preserve source exactly",
"behavior": ["select", "scroll inline", "compose actions outside"]
}One selectable source surface with no toolbar of its own. The AI agents page is the real browsing consumer: Sheet supplies the file identity and Copy/Open raw actions.
Framed is the standalone default. Plain removes only the duplicate boundary and inset when a parent surface already owns both; the source typography and scrolling behavior do not change.
| Frame | Modifier | Best fit |
|---|---|---|
| Framed | — | A standalone snippet in page flow |
| Plain | --plain | A Sheet or another parent that already owns the surface, boundary, and inset |
CodeBlock presents source; it does not become a source browser by itself.
| Verdict | Rule |
|---|---|
| Do | Use CodeBlock for a complete expression, snippet, configuration fragment, or source file preview; use inline Code for one identifier inside prose. |
| Do | Insert source as text, never HTML, and keep ordinary browser selection behavior. |
| Do | Let the host provide filenames, language labels, Copy, Open raw, loading, errors, search, and line selection. |
| Do | Use the framed default in page flow and plain only when a parent surface such as Sheet already supplies the boundary and inset. |
| Don’t | Wrap long lines by default. A visual continuation can look like a real newline and make indentation ambiguous. |
| Don’t | Add a component max-height. Sheet, Dialog, or the page region owns vertical measure and scrolling. |
| Don’t | Turn every line into a focusable control; source remains one readable, selectable document. |