Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): CodeBlock native language set by use, plus importable language modules under one provider (#8286)

Cindy Zhang39b5981914e1
diff --git a/docs/specs/AST-061-document-surface-parity/spec.md b/docs/specs/AST-061-document-surface-parity/spec.md
index c6f60e604a..9ab118672f 100644
--- a/docs/specs/AST-061-document-surface-parity/spec.md
+++ b/docs/specs/AST-061-document-surface-parity/spec.md
@@ -159,6 +159,12 @@ does.
`Markdown`, through `component:CodeBlock`, and the RichText surfaces float
Copy over the code of a fence that names no language; both adopt the FR8
corner cluster that `component:CodeBlock` FR11 places.
+RichText code blocks colour with `component:CodeBlock`'s tokenizer and read the
+same `CodeLanguageProvider` through `useCodeLanguages()` (`component:CodeBlock`
+FR13), so read and edit paint the same languages, except a fence whose first word runs
+past letters, digits, and underscores, such as `c++`, `c#`, `objective-c`,
+`rust,ignore`, or `diff-ts`: `Markdown` reads a fence by its leading word
+characters (`component:Markdown` FR29), while RichText keeps the whole first word.
## Verification
diff --git a/packages/core/src/CodeBlock/CodeBlock.spec.md b/packages/core/src/CodeBlock/CodeBlock.spec.md
index 186489c96d..dc55fc0e77 100644
--- a/packages/core/src/CodeBlock/CodeBlock.spec.md
+++ b/packages/core/src/CodeBlock/CodeBlock.spec.md
@@ -39,15 +39,15 @@ system_specs: [spec:AST-025]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `CodeBlock` and `CodeBlockProps` are exported from `@astryxdesign/core/CodeBlock`; `code` is required, and the remaining released props configure language, header, line presentation, copy, wrapping, sizing, syntax theme, and collapse behavior; `isDiff` (FR9) adds the diff layer as a caller choice over any language; `endContent` (FR10) places caller controls beside Copy. |
-| Behavior | CodeBlock renders a read-only code surface, applies syntax highlighting when available, preserves the source string for copy, and exposes optional line, header, copy, caller-control, theme, and disclosure behavior without editing the content; no control covers the code, and a one-line block with no header (no title, language label hidden) reads as one row (FR11). |
-| End-user impact | Readers can inspect and copy code, understand optional line emphasis, and operate long or collapsible examples with keyboard and assistive technology. Readers of a block with no header never have code under a control, at the cost of the controls' column width, and a one-line command whose label is hidden reads as one row with its controls beside it; product actions sit beside Copy instead of outside the block. |
-| Builder impact | Builders choose the released display axes without an additional migration or opt-in; the diff layer is one more opt-in axis, `endContent` (FR10) is one optional slot for their own controls, and five defaulted syntax-theme slots mean no syntax theme has to change for it. |
-| Compatibility/readiness | The released `CodeBlock` API remains stable and its defaults hold except for the visible headerless layout in Compatibility below (FR11); FR10 (`endContent`, additive) and FR11 are current and await implementation; FR9 (the diff layer) is current and shipped; Markdown's default path for `diff` fences follows it (`component:Markdown` FR29). |
-| Review checks | Reject lost code text, copy of a transformed string, an unnamed copy or disclosure control, stale disclosure state/wiring, dropped root props/ref, a theme target off its painter, viewport focusability that ignores effective overflow, a control painted over the code, or caller controls that toggle the disclosure. |
-| Governing rules | `architecture:public-component-api/INV1,INV5–INV9`; `architecture:component-theming-surface/INV3–INV7,INV12`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`; `spec:AST-025/FR12–FR13`; `architecture:theme-tokens` (syntax vocabulary and the diff slot defaults). |
+| Area | Contract |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `CodeBlock` and `CodeBlockProps` are exported from `@astryxdesign/core/CodeBlock`; `code` is required, and the remaining released props configure language, header, line presentation, copy, wrapping, sizing, syntax theme, and collapse behavior; `isDiff` (FR9) adds the diff layer as a caller choice over any language; `endContent` (FR10) places caller controls beside Copy; `@astryxdesign/core/CodeBlock/languages` exports importable language modules, and `CodeLanguageProvider` and `useCodeLanguages()` turn them on for everything inside a provider (FR13). |
+| Behavior | CodeBlock renders a read-only code surface, applies syntax highlighting when available, preserves the source string for copy, and exposes optional line, header, copy, caller-control, theme, and disclosure behavior without editing the content; no control covers the code, and a one-line block with no header (no title, language label hidden) reads as one row (FR11). |
+| End-user impact | Readers can inspect and copy code, understand optional line emphasis, and operate long or collapsible examples with keyboard and assistive technology. Readers of a block with no header never have code under a control, at the cost of the controls' column width, and a one-line command whose label is hidden reads as one row with its controls beside it; product actions sit beside Copy instead of outside the block. Readers of C, C++, SQL, Rust, Kotlin, Swift, and Go snippets see them highlighted instead of plain (FR12), and so do readers of GraphQL, Java, Thrift, Objective-C, TOML, PowerShell, Ruby, Lua, and Dockerfile snippets wherever the product turns those modules on (FR13). |
+| Builder impact | Builders choose the released display axes without an additional migration or opt-in; the diff layer is one more opt-in axis, `endContent` (FR10) is one optional slot for their own controls, importable language modules under one provider add less common languages (FR13), and five defaulted syntax-theme slots mean no syntax theme has to change for it. |
+| Compatibility/readiness | The released `CodeBlock` API remains stable and its defaults hold except for the visible headerless layout (FR11) and the newly built-in languages (FR12) in Compatibility below; FR10 (`endContent`, additive) and FR11 are current and await implementation; FR12 (built-in languages), FR13 (language modules, additive), and PR4 (their budget) are current and await implementation; FR9 (the diff layer) is current and shipped; Markdown's default path for `diff` fences follows it (`component:Markdown` FR29). |
+| Review checks | Reject lost code text, copy of a transformed string, an unnamed copy or disclosure control, stale disclosure state/wiring, dropped root props/ref, a theme target off its painter, viewport focusability that ignores effective overflow, a control painted over the code, or caller controls that toggle the disclosure. |
+| Governing rules | `architecture:public-component-api/INV1,INV5–INV9`; `architecture:component-theming-surface/INV3–INV7,INV12`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`; `spec:AST-025/FR12–FR13`; `architecture:theme-tokens` (syntax vocabulary and the diff slot defaults). |
This table is a review projection; the body below is authoritative only after owner approval.
@@ -57,10 +57,12 @@ Present read-only, standalone or multi-line code with optional syntax, navigatio
## Compatibility and migration
-- Released default preserved: yes, except the visible headerless layout (FR11, below)
+- Released default preserved: yes, except the visible headerless layout (FR11) and the newly built-in languages (FR12), below
- Compatibility class: compatible; no prop, export, type, default, target, or ref migration is required
- Controlled/uncontrolled behavior: collapse state remains component-owned, starts expanded when applicable, and returns to expanded when its control disappears
- Visible default change (FR11), not breaking: a block with no header shows its controls in their own column beside the code instead of over it, so its code ends that much earlier, a block sized to its content (`fit-content`) grows by the column's width, and a one-line block reads as one row. A block with a title or a visible language label keeps its header at every line count. Markdown fences with no language take it through the default code path (`component:Markdown`). No prop, type, or target migration follows from it.
+- Visible default change (FR12), not breaking: blocks and Markdown fences in the newly built-in languages are highlighted instead of plain, and the exported `tokenize`, `tokenizeAsync`, and `tokenizeStreaming` functions, with the RichText code blocks and editors that call them, return tokens for those identifiers; text, copy output, labels, and a custom `tokenizer` are unchanged, and the built-in tokenizer grows within the PR4 budget. Markdown fences reach these identifiers by their leading word characters (`component:Markdown` FR29): a `cpp` fence highlights as C++, while a `c++` fence reads as `c`.
+- Additive API (FR13): `@astryxdesign/core/CodeBlock/languages`, `CodeLanguageProvider`, `useCodeLanguages()`, and the optional modules argument of the exported tokenize functions are new; nothing changes until a product imports a module and renders the provider.
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
@@ -80,19 +82,19 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |
-| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------- | ------------------- | --------- | --------------------------------------------------------------------- |
-| code content | caller-supplied string | Supplies the exact read-only source that is displayed and copied. | Every render | required | product callsite | stable | rejected by the public type |
-| language | built-in identifier, custom-tokenizer identifier, or plaintext/unknown | Selects tokenization and the optional visible/accessible language label. | Every render | `plaintext` | component:CodeBlock | stable | unsupported built-ins render without tokens |
-| line presentation | numbers off/on; highlights absent or one-indexed line set; wrapped/unwrapped | Adds navigation and emphasis without changing the copied source string. | Code body | off/absent | component:CodeBlock | stable | out-of-range highlights have no rendered line |
-| diff layer | off; on — each line classified by its first character: `+` added, `-` removed, header (`@@`; a `--- `/`+++ ` pair directly before an `@@`), else context | Tints added and removed rows and quiets header rows from the syntax theme while the rest of every line keeps the base language's syntax paint; the glyph stays in display and copy. | Code body, any `language` | off | product callsite | stable | rejected by the public type (boolean) |
-| header | absent; title; language label; title and language label | Gives the snippet context and houses the caller controls and copy when it exists. | Derived from title and label choices | derived | component:CodeBlock | stable | empty visible content still requires AT naming |
-| copy | hidden; available; transient copied feedback | Copies the exact code string, then invokes `onCopy` only after a successful clipboard write. | Every render when enabled | available | component:CodeBlock | stable | failed clipboard writes do not invoke `onCopy` |
-| caller controls (`endContent`) | absent; caller-rendered nodes | Places product actions beside Copy, before it in reading order, in the header or the corner cluster; never creates the header. | Every render | absent | product callsite | stable | any React node; CodeBlock does not inspect it |
-| corner cluster | absent; caller controls and copy, in that order | Holds the controls of a block with no header in their own inline-end column beside the code, centred on the first line. | Blocks with no header and any control | derived | component:CodeBlock | stable | an empty cluster takes no column |
-| syntax rendering | auto; CSS ranges; spans; custom tokenizer; optional per-instance syntax theme | Selects a supported paint path without changing the text or public code semantics. | Every render | `auto` | component:CodeBlock | stable | unsupported range capability falls back to spans |
-| collapse | unavailable; expanded; collapsed | Turns an eligible visible header into a disclosure when the line threshold is met. | Long blocks with a header and collapse enabled | unavailable | component:CodeBlock | stable | missing-header or below-threshold blocks remain expanded and ordinary |
-| container geometry | card/section; small/medium; fit-content/custom width; unbounded/bounded height | Selects presentation and overflow geometry while preserving the read-only code task. | Every render | card/md | component:CodeBlock | stable | values follow their documented CSS/type behavior |
+| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------- | ------------------- | --------- | --------------------------------------------------------------------------------------------------- |
+| code content | caller-supplied string | Supplies the exact read-only source that is displayed and copied. | Every render | required | product callsite | stable | rejected by the public type |
+| language | built-in identifier (FR12), language-module identifier inside a provider (FR13), custom-tokenizer identifier, or plaintext/unknown | Selects tokenization and the optional visible/accessible language label. | Every render | `plaintext` | component:CodeBlock | stable | an identifier with no built-in grammar, provided module, or custom tokenizer renders without tokens |
+| line presentation | numbers off/on; highlights absent or one-indexed line set; wrapped/unwrapped | Adds navigation and emphasis without changing the copied source string. | Code body | off/absent | component:CodeBlock | stable | out-of-range highlights have no rendered line |
+| diff layer | off; on — each line classified by its first character: `+` added, `-` removed, header (`@@`; a `--- `/`+++ ` pair directly before an `@@`), else context | Tints added and removed rows and quiets header rows from the syntax theme while the rest of every line keeps the base language's syntax paint; the glyph stays in display and copy. | Code body, any `language` | off | product callsite | stable | rejected by the public type (boolean) |
+| header | absent; title; language label; title and language label | Gives the snippet context and houses the caller controls and copy when it exists. | Derived from title and label choices | derived | component:CodeBlock | stable | empty visible content still requires AT naming |
+| copy | hidden; available; transient copied feedback | Copies the exact code string, then invokes `onCopy` only after a successful clipboard write. | Every render when enabled | available | component:CodeBlock | stable | failed clipboard writes do not invoke `onCopy` |
+| caller controls (`endContent`) | absent; caller-rendered nodes | Places product actions beside Copy, before it in reading order, in the header or the corner cluster; never creates the header. | Every render | absent | product callsite | stable | any React node; CodeBlock does not inspect it |
+| corner cluster | absent; caller controls and copy, in that order | Holds the controls of a block with no header in their own inline-end column beside the code, centred on the first line. | Blocks with no header and any control | derived | component:CodeBlock | stable | an empty cluster takes no column |
+| syntax rendering | auto; CSS ranges; spans; custom tokenizer; optional per-instance syntax theme | Selects a supported paint path without changing the text or public code semantics. | Every render | `auto` | component:CodeBlock | stable | unsupported range capability falls back to spans |
+| collapse | unavailable; expanded; collapsed | Turns an eligible visible header into a disclosure when the line threshold is met. | Long blocks with a header and collapse enabled | unavailable | component:CodeBlock | stable | missing-header or below-threshold blocks remain expanded and ordinary |
+| container geometry | card/section; small/medium; fit-content/custom width; unbounded/bounded height | Selects presentation and overflow geometry while preserving the read-only code task. | Every render | card/md | component:CodeBlock | stable | values follow their documented CSS/type behavior |
## Behavioral and layout contract
@@ -109,6 +111,8 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR9 | With the diff layer on (`isDiff`), CodeBlock MUST classify each line by its first character — `+` added, `-` removed, `@@` header, anything else context — except that a `--- ` line (three minus signs and a space, the unified-diff file header form) directly followed by a `+++ ` line and then an `@@` line is a file header (both lines), wherever it occurs; every other `---`/`+++` line, `---i;` included, is removed or added. CodeBlock MUST set the glyph column aside and tokenize the REST of every line (context, added, and removed alike) with the base `language`'s syntax highlighting. Added, removed, and header lines MUST paint as whole rows — the line-number gutter cell included — from the syntax-theme slots `--color-syntax-added`, `--color-syntax-removed`, and `--color-syntax-diff-header`, whose defaults `architecture:theme-tokens` owns; header rows take the syntax theme's `punctuation` colour as text (`--color-text-secondary` in the default theme) and never change paint; context rows keep ordinary paint. On an added or removed row, the line number and the glyph take the row's marker slot — `--color-syntax-added-marker` / `--color-syntax-removed-marker` — so the margin reads the change in colour; every run of code text, painted by a token or not, keeps its syntax-theme colour. In the Astryx default syntax theme the marker slots default to the theme's tinted-text tokens and the header paint to the muted background (`architecture:theme-tokens` owns the values); a syntax theme that does not set them inherits its own colours — the marker slots and the header text its line-number colour (its `punctuation` slot), the header paint none at all (the header row sits on the theme's own syntax background) — so number, glyph, and header text stay legible on that theme's background in every page mode, and the glyph's shape carries the meaning where its colour does not. The glyph (`+`, `-`, the leading space of a context line, or nothing for a context or header line without one — the marker column is then empty and the whole line is code) MUST render in its own fixed-width marker column — secondary colour on context rows and the row's marker slot on added and removed rows, separated from the code by a token gap (`--spacing-2`, a proportion themes may vary like the rest), excluded from selection for layout yet present in the copied text — so the code column starts at the same inline offset on every line and the content's own indentation is never shifted; the gutter order is line number, marker, code, mirrored in RTL with the code's direction unchanged. The header (language label, copy, disclosure) and the viewport's name stay as for any other code: with the layer over plaintext the visible language label and the viewport name are `diff`, and over a language they name both (`tsx diff`). Markdown's fence mapping onto the layer is `component:Markdown` FR29. Row paint MUST compose with line numbers without moving text; on a highlighted added, removed, or header line the highlight REPLACES the row paint rather than stacking on it, so text keeps its single-paint contrast; and row paint MUST span the full line width — the scrolled overflow of a long line included, in wrapped and unwrapped mode — not only the visible viewport. Contrast floor: in the Astryx default syntax theme, every default token colour and the row's marker slot (line number and glyph) on a painted row MUST measure ≥ 4.5:1 against the default tints composited over the code block's own `--color-syntax-background` on the default card surface. In a syntax theme that overrides a diff slot, a token that already measures under 4.5:1 on that theme's own syntax background MUST NOT drop further on the slot, and every other token MUST clear 4.5:1 on it. Two known shortfalls, tracked separately: the shipped syntax presets do not yet meet the floor on the default tints with the layer on, and shipped page themes whose own text tokens fall under it on the tints keep that shortfall, tracked for a fix in those themes, until each sets its tokens or the diff slots. | this record DEC-1 | current; owner-approved 2026-10-12 |
| FR10 | `endContent` MUST render the caller's nodes beside Copy and before it in reading order: in the header when one exists, otherwise in the corner cluster (FR11); without Copy it keeps that place. It MUST sit outside the disclosure control, and pointer or keyboard activation inside it MUST NOT toggle collapse. CodeBlock MUST NOT name, restyle, or announce its content; the caller owns each control's name, state, and action. | proposal; the end-content slot of the Dialog and Drawer headers | verify |
| FR11 | With no header, the corner cluster MUST occupy its own inline-end column beside the code viewport, as wide as its content and never over the viewport, so that no line, at rest, scrolled, wrapped, or in either direction, is painted under a control; the cluster MUST be centred on the first line of code. A headerless block whose code is one line — counted after removing one trailing newline — therefore reads as one row: code, then the controls, with even space above and below; the single-line mode a caller gets by leaving out the title and passing `hasLanguageLabel={false}`. When the code gains lines, the block grows downward and the controls keep their place. A visible language label or a title keeps the header at every line count (FR3). The column paints from the `code-block` root, so no theme target is added. | the Code Body and Copy Button design relationships; proposal | verify |
+| FR12 | Without a custom tokenizer, CodeBlock MUST paint syntax for these built-in identifiers and their aliases: `typescript`/`ts`, `javascript`/`js`, `tsx`, `jsx`; `json`; `html`, `xml`, `svg`; `css`, `scss`, `less`; `python`/`py`; `bash`, `sh`, `zsh`, `shell`; `php`; `hack`; `yaml`/`yml`; `markdown`/`md`; `c`, `h`; `cpp`, `c++`, `cc`, `cxx`, `hpp`, `hh`; `sql`; `rust`/`rs`; `kotlin`, `kt`, `kts`; `swift`; `go`/`golang`. Each built-in paints the comment, string, number, and keyword tokens its language has from the syntax theme. Any other identifier renders as plain code with its label unless a language module (FR13) or a custom tokenizer paints it. | proposal | verify |
+| FR13 | `@astryxdesign/core/CodeBlock/languages` MUST export one language module per family: `graphql` (`graphql`, `gql`), `java` (`java`), `thrift` (`thrift`), `objectiveC` (`objective-c`, `objc`, `m`, `mm`), `toml` (`toml`), `powershell` (`powershell`, `ps1`, `pwsh`), `ruby` (`ruby`, `rb`), `lua` (`lua`), and `dockerfile` (`dockerfile`, `docker`). Inside `CodeLanguageProvider` with `languages` listing modules, CodeBlock — and every surface that colours code with CodeBlock's tokenizer, Markdown fences and RichText code blocks included — MUST paint those identifiers as it paints a built-in, in the same render as a built-in would; a nested provider adds its modules to the outer set. A block's own `tokenizer` MUST take precedence over provided modules, and provided modules over built-ins. Outside any provider a module identifier renders as plain code with its label. `@astryxdesign/core/CodeBlock` exports `CodeLanguageProvider` and `useCodeLanguages()`, which returns the modules the nearest providers turn on, and the exported `tokenize`, `tokenizeAsync`, and `tokenizeStreaming` take those modules as an optional last argument, so a surface outside CodeBlock that colours code, such as RichText, paints the same languages. Modules are opaque values: CodeBlock exposes no grammar format, and no state outlives a provider. | proposal | verify |
### Allowed variation
@@ -138,6 +142,7 @@ Consumer migration instructions belong in consumer docs and release notes.
- **PR1 — Tokenization.** Short code may tokenize synchronously; long built-in code yields through the async tokenizer and cancels stale work when code or language changes.
- **PR2 — Highlight lifetime.** Range-mode highlighting removes ranges and visibility listeners when its rendered token set changes or unmounts.
- **PR3 — Large line sets.** Large blocks may chunk line rendering and use content visibility, without losing source order or line identity.
+- **PR4 — Language budget.** The built-in tokenizer, every FR12 grammar included, stays within 4,608 bytes minified and gzipped, and each FR13 module adds at most 512 bytes minified and gzipped to a bundle that imports it; nothing loads at run time, so short code paints in its first render (PR1) and no block waits on the network.
## Accessibility contract
@@ -186,6 +191,7 @@ Exact CodeBlock proportions and syntax colors are not contract requirements; the
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| FR1, PR1–PR3 | `tokenizer.test.ts`; `highlightRanges.test.ts`; CodeBlock focused tests and built Storybook | short/long, built-in/custom, ranges/spans, empty lines | Text changes, stale tokens paint, ranges leak, source order changes, or long work stops yielding/canceling. | `audit:CodeBlock/behavior` |
+| FR12, FR13, PR4 | `tokenizer.test.ts` (one representative snippet per built-in family and alias, and per module inside a provider: the comment, string, number, and keyword tokens each language has; an unknown identifier yields no tokens); CodeBlock, Markdown, and RichText tests (a module identifier paints inside a provider and not outside it; nested providers add; a block `tokenizer` wins; server rendering paints in the first render); a size check over the minified, gzipped tokenizer and each module | every FR12 identifier and alias, every FR13 module and alias inside and outside a provider, nested providers, an unknown identifier, an empty string | A listed identifier renders without tokens, an alias paints differently from its family, a module paints outside its provider or not inside it on any of the three surfaces, a block tokenizer loses to a module, source text changes, the tokenizer exceeds 4,608 bytes, or a module adds more than 512 bytes, minified and gzipped. | `audit:CodeBlock/behavior` |
| FR2, AR1, AR3 | `CodeBlock.test.tsx`; component-scoped accessibility audit | copy success, rapid repeat, localized feedback, empty title | Exact source is not copied, callback fires on failure, announcement is absent/duplicated, or a control is unnamed. | `audit:CodeBlock/a11y` |
| FR3–FR5, AR2 | `CodeBlock.test.tsx`; `CodeBlock.stories.tsx`; exact-head browser evidence | headerless, titled, zero max height, line options, collapse/control removal | Header/copy placement changes, zero is dropped, disclosure state/wiring/keyboard behavior breaks, or inert outlives its control. | `audit:CodeBlock/behavior` |
| FR6 | `themingTargets.test.ts`; consumer docs; source review | root, header, title, copy; current and deprecated names | A target leaves its painter, an axis stops reflecting, or a deprecated alias disappears before authorization. | `audit:CodeBlock/theming` |
@@ -219,6 +225,12 @@ A product that gives a snippet a second verb, such as running a command in a ter
A control painted over code hides the reader's text, so a headerless block's controls sit in their own inline-end column beside the code viewport, as wide as the controls themselves; the column runs the block's full height because a scroll box clips its lines as one rectangle. Centring the column on the first line makes a headerless one-line block read as one row with even space and keeps the controls still while a block grows line by line, so a streamed block never moves its controls. Single-line mode is the existing choice to hide the language label: a caller that shows the label keeps the header and its context at every line count, and one that hides it gets the row. The column has no width cap; the caller supplies a few icon controls, and the code viewport takes the rest. Rejected: folding a visible label into a one-line row (the label is context the caller chose to show, and a streamed block would move its code when the label returned to a header); reserving space on the first line only (a scrolled line still runs under the control).
+### DEC-4 — A native language set chosen by use; the rest are modules turned on by one provider
+
+**Decider:** `cixzhang`, `2026-10-24`
+
+A reader sees a short snippet highlighted in its first render (PR1), with no product setup, for the languages people write most: the native set is the 11 families CodeBlock already knows plus C and C++, SQL, Rust, Kotlin, Swift, and Go, which together cover about 97% of fences that name a language in a large engineering Markdown corpus, inside a 4,608-byte budget every consumer pays. Less common languages are opt-in modules, so a product pays only for the ones it imports; one scoped provider turns them on for CodeBlock, Markdown fences, and RichText code blocks alike, because those surfaces render blocks with no per-block props, and read and edit must paint the same languages. Modules are opaque so the grammar format stays internal; any other language uses the `tokenizer` prop. Rejected: every family built in (every consumer pays for the long tail, and the set cannot grow); a per-block `languages` prop (Markdown and RichText could not pass it); a global registry (state shared across React roots and requests); loading grammars on demand (a block would paint plain, then recolour, and wait on the network).
+
## Open questions
None.