brookmd 0.25.2 → 0.26.1

package/CHANGELOG.md

@@ -4,6 +4,260 @@ Notable changes to brookmd (formerly `flux-md`). Format based on
 [Keep a Changelog](https://keepachangelog.com/); this project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## 0.26.1 — 2026-07-30
+
+Two fixes found by benchmarking 0.26.0 against real chat traffic. Requires
+`brookmd-core` 0.25.1.
+
+### Fixed
+
+- **A GFM table could not interrupt an open paragraph — anywhere.**
+  `scan_paragraph` had no table arm, so `item\n| a | b |\n|---|---|` swallowed
+  the delimiter row as paragraph text. The visible symptom was "tables inside
+  list items don't parse" (an item's de-indented body opens with a paragraph),
+  but the bug was position-independent and hit top level and blockquotes the
+  same way. The fix is an O(2-line) gate — header row with a pipe, delimiter
+  row next, matching cell counts, both rows indented ≤ 3 columns — checked once
+  per line as it arrives, on both the full-reparse and streaming paths, so a
+  scan started at a commit boundary renders byte-identically to a cold one.
+  Verified against GitHub's rendering for every non-pathological shape; the
+  deliberate exception (both rows must be ≤ 3-indented, so two exotic
+  mixed-indent shapes stay paragraphs) is pinned in `tests/nested_tables.rs`.
+  A nested table renders inside the item's `html` and — like nested lists —
+  carries no structured `blockData` of its own.
+
+### Performance
+
+- **Close-time syntax highlighting no longer blocks the main thread.** The
+  built-in highlighter ran as one synchronous task when a block closed —
+  ~110 ms for a large fence on a mid desktop. The tokenizer loop was already
+  resumable at any offset with no carried state, so it now runs in ~5 ms
+  slices (`scheduler.yield()` where available, `MessageChannel` otherwise),
+  with the first slice synchronous so small blocks render highlighted in the
+  same tick with no flash. Output is byte-identical — pinned by a chunked ==
+  one-shot property test across all 20 languages at chunk sizes down to 1,
+  plus a 6,556-case differential fuzz against the previous implementation.
+  Also: the renderers now reuse the parser's already-decoded source
+  (`CodeBlockData.code`) when `blockData` is on instead of re-deriving it from
+  the HTML, and `escapeHtml` no longer concatenates per character. A 49 KB
+  block's longest main-thread task drops from ~38 ms to ≤ 6 ms on the same
+  hardware; `highlight()`'s public signature and bytes are unchanged, SSR
+  stays synchronous, and `components.CodeBlock`/`pre`/`code` overrides are
+  unaffected.
+
+## 0.26.0 — 2026-07-30
+
+**Rendered HTML bytes change in this release.** Everything new below is opt-in
+and default-off — with the flags off those paths are byte-identical to 0.25.2 —
+but the output-fidelity work is unconditional: container framing newlines,
+paragraph whitespace, table line breaks, fenced-code indentation, and the
+task-list checkbox form now match the CommonMark and GFM reference renderers
+exactly. No API is removed, and the wire envelope, ids, and commit semantics are
+untouched — but HTML snapshots taken against 0.25.x will need regenerating.
+That, not the new features, is why this is a minor bump.
+
+What it buys: **652/652 CommonMark 0.31 and 24/24 GFM, byte-exact** against the
+reference renderers, where before the suites passed only after structural
+normalization. Byte-exactness is now the harnesses' default floor and is pinned
+in CI, so one regressed byte fails the build.
+
+Requires `brookmd-core` 0.25.0.
+
+### Added
+
+- **`softBreaks` — a soft line break renders as `<br>`.** Strict CommonMark
+  treats a bare `\n` inside a paragraph as whitespace, so a model that writes one
+  thought per line gets one reflowed blob. This is the `remark-breaks` /
+  chat-comment convention where one Enter is one visual line, and it is what most
+  chat UIs actually want. Off by default; it only ever *adds* breaks (a hard break
+  is `<br>` either way), so no existing output loses a line.
+- **`allowSchemes` — un-block a URL scheme brookmd blocks by default.** Bare
+  scheme names, no colon (`allowSchemes: ["file"]`), matched case-insensitively.
+  It reaches exactly one tier: the *overridable*-blocked schemes, today `file:`.
+  The script-executing tier (`javascript:`, `data:text/html`, …) is
+  non-overridable — listing one is a silent no-op, not an escape hatch — and the
+  encoded-evasion neutralization (percent- and entity-encoded scheme prefixes) is
+  unchanged and runs before the check. This exists for privileged embedders —
+  Electron shells, extensions, editor preview panes — that intercept link clicks
+  instead of navigating.
+- **`lenientLists` — rescue an over-indented list item from becoming a code
+  block.** CommonMark §5.2 says a marker followed by 5+ columns of whitespace
+  starts an indented code block, so a model emitting `-       const value = 1;`
+  renders a `<pre><code>` instead of a list item. With the flag on, a marker
+  followed by **6 or more columns of literal spaces** absorbs the padding into the
+  content column and the text parses as the item's own markdown. Deliberately
+  narrow: exactly 5 spaces still opens code (that column is the spec boundary
+  itself), a fence on the marker line stays a fence, an indent on a *later* line
+  stays code, and **tab** padding stays code — tabs are an authoring choice, model
+  over-indentation is always literal spaces. Excluding tabs is what holds the
+  divergence to a single spec example (274) and only while the flag is on; the
+  conformance suites run strict and are unaffected.
+- **`blockHtml` — block-level raw HTML through the safe sanitizer.** A
+  `<details><summary>…</summary>…</details>` block rendered as an escaped code
+  block before; now it renders as real elements, sanitized. Only CommonMark HTML
+  block **types 6 and 7** qualify — types 1–5 (`<script>`/`<pre>`/`<style>`/
+  `<textarea>`, comments, processing instructions, declarations, CDATA) stay
+  escaped by design, so the constructs that can execute or swallow the rest of
+  the document never take effect.
+  It shares its token core with the inline raw-HTML path (one policy, not two),
+  tracks an open-tag stack with speculative closers so a half-streamed
+  `<details` never leaks a broken element, carries a void-element table so `<hr>`
+  and friends are not pushed onto that stack, and caps nesting depth at 100.
+  Half-streamed tags are suppressed while open and settle at finalize. Takes
+  effect only when the sanitizer is engaged (`htmlAllowlist` or `dropHtmlTags`);
+  on its own it does nothing.
+- **`CodeBlockData.meta` — the fence info string's remainder.**
+  ```` ```ts title="src/main.ts" ```` now yields `lang: "ts"` **and**
+  `meta: 'title="src/main.ts"'` on the data channel and as a `meta` prop on
+  `components.CodeBlock`. Always-on like `lang` (no `blockData` needed) and
+  omitted entirely when the fence carried none, so a fence without meta is
+  byte-identical to before. It is deliberately **not** in the rendered HTML —
+  there is no `data-meta` attribute — because a filename header is a component's
+  job, not the parser's. While streaming it appears only once it can no longer
+  change (the opening fence line terminated by a newline, or at finalize), so a
+  header never flickers through a half-typed `title="src/ma`.
+- **`ListItemData.start` — a source byte offset per list item.** Under
+  `blockData`, each top-level `items[]` entry carries the document-absolute offset
+  of the byte where its marker begins, same origin as `Block.start` and stable as
+  the document grows. That is enough to build task-checkbox writeback: locate the
+  `[ ]` from the item's offset and flip it in the original markdown, no HTML
+  round-trip. **Nested** items carry no offset rather than a wrong one — a nested
+  list is not a separate block, it renders against a synthesized de-indented
+  string with no document offset — and that limitation is documented on the type.
+- Together `meta` and `start` bump the **wire contract to 1.3.0** (WIRE.md §9):
+  purely additive optional `data` keys, byte-identical when unexercised.
+- All four flags are plumbed through every surface: client/worker config, the
+  server renderer, the `<brook-markdown>` element (`soft-breaks`,
+  `lenient-lists`, `block-html`, `allow-schemes`), React Native, Kotlin, Swift,
+  and the Flutter hand-written config.
+- **Byte-exact conformance mode in the spec harnesses**, with default ratchet
+  floors `CMARK_MIN_EXACT=652` / `GFM_MIN_EXACT=24` — pinned explicitly in both
+  the CI and publish workflows alongside the older normalized floors. The four
+  deliberate differences from the reference (`target`/`rel` on links, `data-lang`
+  on code blocks, HTML5 void `<br>`, `style="text-align:…"` instead of GFM's
+  deprecated `align`) are folded by a documented `canonicalize` step applied to
+  **both** sides — the only transform on the byte-exact path, so it can erase our
+  intentional extras but never hide a structural divergence.
+- **An unconditional `bindings` CI job** — FFI and C-ABI crate tests plus
+  regeneration-freshness checks for the React Native, Kotlin, and Swift bindings.
+  The existing binding workflows only ran on `pull_request` behind `paths:`
+  filters, so a push to main or a JS-only PR gated on nothing; that is how stale
+  binding goldens survived.
+
+### Changed
+
+- **Container inner newlines now match the reference exactly** (cmark's `cr()`
+  rule): `<li>` / `<blockquote>` / alert framing newlines land where the
+  reference puts them, an empty blockquote gets its newline, and a `<li>` opening
+  with a tight paragraph no longer emits a spurious `\n`.
+- **Paragraph whitespace follows the spec line by line.** Leading indentation is
+  stripped on *every* line, not just the first; trailing spaces and tabs are
+  dropped before a soft break; a hard-break line sheds the *next* line's indent.
+  Lazy continuation lines in blockquotes and lists keep their `\n` instead of
+  being glued with a space.
+- **GFM tables emit one element per line**, matching the reference's framing, and
+  task-list checkboxes emit the reference byte-form
+  (`checked="" disabled="" type="checkbox"`).
+- **Fenced code**: the body is de-indented by the opening fence's own indent (so
+  a fence at columns 1–3 no longer carries that indent into every line);
+  significant trailing spaces inside the last line are preserved; interior blank
+  lines before the closer are preserved. Tab-column arithmetic is fixed after
+  blockquote markers, across item-content boundaries, and after list markers.
+- **Document assembly is now defined and documented** ([WIRE.md
+  §12](../../crates/brookmd-core/WIRE.md)): a block's `html` carries **no
+  trailing newline** — the terminator after a top-level block belongs to the
+  document, not the block — and concatenating blocks is a `cr()`-join.
+  `renderToString` follows that rule, so a server-rendered document and a
+  reference render agree byte-for-byte.
+- **Native `BrookConfig` gained four fields** (`soft_breaks`, `allow_schemes`,
+  `lenient_lists`, `block_html`), appended in a newly documented **append-only
+  zone**: uniffi serializes a record's fields *positionally*, so inserting a field
+  anywhere above shifts every later read. The wire was verified to be
+  exact-consumption — a binding built against the old record fails loudly on a
+  version mismatch rather than silently mis-decoding — and the RN, Kotlin, and
+  Swift bindings are regenerated, with the Flutter hand-written config synced
+  (it also gained the previously-missing `wire_delta`). Stale wire goldens across
+  all four languages were re-synced. `brookmd-ffi` and `brookmd-cabi` go to
+  **0.3.0**: the native library and its generated bindings must ship in lockstep.
+
+### Performance
+
+Every item below is pinned by a **wall-time** regression guard in
+`crates/brookmd-core/tests/scaling.rs`, each paired with a flush-control twin
+that isolates the shape from its chunking. That pairing is the point: work
+counters alone provably miss the allocation-class quadratics below — the parser
+was doing O(n) *counted* work while re-allocating O(n) bytes per append, so only
+the clock could see it.
+
+| Shape | Measured as | Before | After |
+| --- | --- | --- | --- |
+| growing fence opener line | growth over an 8× input span | 50.5× | **9.1×** |
+| indented continuation lines | vs the unindented control | 304.6× | **1.1×** |
+| ragged chunks parked on a blank partial line | vs control | 110.2× | **1.1×** |
+| the same, inside a list item | work counters | 212× | **12.8×** |
+| block-HTML sanitize | vs the escaped control | 247× | **1.3×** |
+
+- **Fence opener-line growth** re-sliced the whole opener on every append —
+  quadratic in the info string's length. Now linear-ish: 9.1× over an 8× span.
+- **Indented continuation lines** made `is_boundary` produce *zero* cut
+  candidates, so every append re-rendered the entire paragraph from its start. A
+  new indent-led boundary rule (with a hard-break-straddle exclusion) restores
+  cutting; the shape now costs 1.1× its unindented control.
+- **Ragged chunking that parks on a whitespace-only partial line** dropped the
+  paragraph cache outright, forcing a full rebuild per append. The cache now
+  **suspends instead of dropping**: the closed view stays byte-identical and the
+  parse resumes when the line completes. List items inherit the fix through the
+  nested parser.
+- **Block-level raw HTML** would otherwise re-sanitize its whole body per append
+  (measured 247×); the sanitize cache folds at token boundaries, shipping at 1.3×
+  the cost of the escaped control. Container, table-cell, and heading caches were
+  proven structurally immune to the same class and are pinned so they stay that
+  way.
+
+### Security
+
+- **The raw-HTML attribute policy is now an explicit dropped-attribute table**
+  rather than scheme-checking alone: `srcdoc`, `is`, `autofocus`,
+  `contenteditable`, the DOM-clobbering `id` / `name`, the shadow-piercing
+  `slot` / `part` / `exportparts`, the `form*` family, the `xmlns:` / `xlink:`
+  prefixes, and `ping`. `formaction` and `ping` are **dropped outright** — for a
+  URL carrier that re-targets a form or fires a background beacon, dropping is
+  strictly stronger than validating its scheme. Component-tag props stay
+  permissive by design (they are consumer-mediated — your component decides what
+  to do with them, and they never become DOM attributes); that asymmetry is now
+  documented rather than incidental.
+- **The web component's `gfm-tagfilter` attribute was never observed.** It was in
+  the element's config map but missing from `observedAttributes`, so it applied at
+  mount and then silently ignored every later change — a security-relevant flag
+  that could not be turned on after the fact. Fixed, and the list now carries a
+  comment tying it to the map so the next flag cannot repeat it.
+
+### Fixed
+
+- **A mid-stream committed-view divergence**: a cut taken after a *single*
+  inter-word space could straddle the hard-break lookbehind, so a paragraph
+  containing entity-produced spaces rendered differently mid-stream than it did
+  one-shot. The streamed view now matches the one-shot render at every chunk
+  boundary again.
+
+## brookmd-react-native 0.1.7 — 2026-07-30
+
+### Added
+
+- `softBreaks`, `allowSchemes`, `lenientLists`, and `blockHtml` on the native
+  `BrookConfig`, reaching the on-device parser through the same JSI path as the
+  existing flags. The generated TS/C++ bindings are regenerated from
+  `brookmd-ffi` 0.3.0 and are now freshness-checked on every push by the new CI
+  `bindings` job.
+
+### Changed
+
+- `brookmd` dependency range `^0.25.0` → `^0.26.0`, and the vendored native
+  binaries are built against `brookmd-core` 0.25.0 — so the on-device renderer
+  produces the same reference-exact bytes as the browser. Native and JS must move
+  together here: uniffi records are positional, and the four new `BrookConfig`
+  fields land in the record's append-only zone.
+
 ## 0.25.2 — 2026-07-27
 
 Performance only. Rendered output is unchanged — byte-identical mid-stream, not

package/README.md

@@ -461,6 +461,17 @@ export default function Doc({ md }: { md: string }) {
 - **`renderToString(md, { config })`** — synchronous HTML string, **zero React
   dependency** (imports cleanly with no `react` installed).
 - **`parseToBlocks(md, { config })`** — the block array, for custom rendering.
+
+**Document assembly.** A `Block.html` never ends with a newline — the terminator
+that follows a top-level block belongs to the *document*, not the block.
+`renderToString` therefore joins blocks with cmark's `cr()` rule: insert `\n`
+before a block only when the output doesn't already end with one, and end the
+document with one `\n`. An unconditional `"\n".join(...)` would double the
+newline a raw HTML block serializes for itself. **If you assemble
+`parseToBlocks` output into a document string yourself, use the same rule** —
+it's what makes the output byte-identical to a reference CommonMark/GFM renderer
+(652/652 CommonMark 0.31 and 24/24 GFM extension examples, byte-for-byte). See
+`WIRE.md` §12.
 - **`<BrookMarkdownStatic content config components />`** (from
   `brookmd/server/react`) — synchronous React tree for **render-once** contexts;
   render it with your framework's server renderer
@@ -614,12 +625,16 @@ const client = new BrookClient({
     gfmFootnotes: true,   // [^1] + [^1]: → footnote section (default false)
     gfmMath: true,        // $…$ / \(…\) inline + $$…$$ / \[…\] display math (default false)
     dirAuto: true,        // per-block dir="auto" for RTL/bidi text (default false)
+    softBreaks: true,     // a single \n renders as <br> (remark-breaks / chat convention; default false)
+    lenientLists: true,   // marker + 6+ SPACES → item text, not indented code (default false)
     a11y: true,           // task-list <label> + <th scope="col"> a11y markup (default false)
     unsafeHtml: false,    // pass raw HTML through (default false — keep it false for untrusted input)
     componentTags: ["Thinking", "Callout"], // BLOCK custom tags w/ markdown inside (default none)
     inlineComponentTags: ["tik", "cite"],   // INLINE custom tags (chips/citations) w/ markdown inside (default none)
     htmlAllowlist: ["br", "sub", "sup"],    // safe raw-HTML sanitizer: [] = allow all but dangerous; list = only those (default off)
     dropHtmlTags: [],                        // tags removed entirely (comments always dropped when sanitizing; default off)
+    blockHtml: true,                         // extend the sanitizer to BLOCK raw HTML (<details>…); needs a list above (default false)
+    allowSchemes: ["file"],                  // un-block a default-blocked URL scheme (default none — see "Security")
     blockData: true,      // opt-in structured kind.data per block (default false — see "Structured block data")
   },
 });
@@ -640,6 +655,32 @@ When to enable each flag:
   definitions. Off by default; see the footnote streaming caveat above.
 - `dirAuto: true` — when content can be RTL / mixed-direction. Emits per-block
   `dir="auto"` so the browser detects direction independently per block.
+- `lenientLists: true` — when your LLM over-indents after a list marker. Strict
+  CommonMark (§5.2) says a marker followed by **5 or more** columns of
+  whitespace starts an indented code block, so a model writing
+  `-       const value = 1;` renders as a `<pre><code>` block instead of a list
+  item. This flag raises that cutoff to **6 columns of literal spaces**: at 6+
+  the padding is absorbed into the item's content column and the text renders
+  as the item's own markdown (inline formatting, links, and nested lists all
+  parse normally). Off by default, so strict-CommonMark output is unchanged.
+
+  Four cases stay strictly conformant **by design** — the flag is deliberately
+  narrow, not a general "fix my indentation" pass:
+
+  | Input | Stays | Why |
+  | --- | --- | --- |
+  | `-` + exactly 5 spaces | code block | 5 columns is the §5.2 boundary itself; relaxing it would swallow genuine one-space-past-the-minimum code |
+  | `` - ```js `` (fence on the marker line) | fenced code | the marker line opens a real fence — there is no over-indentation to undo |
+  | `-` then code indented on a **later** line | code block | the decision reads only the marker's own line; a later-line indent is unambiguous authored code |
+  | `-\t\tfoo` (tab padding) | code block | tab padding is a deliberate authoring choice, unlike model over-indentation which is always literal spaces |
+
+  Excluding tabs is what keeps the divergence from CommonMark down to a single
+  spec example (274, `1.` + 6 spaces). Everything else in the 652-example suite
+  renders identically with the flag on or off; the conformance suites
+  themselves run in strict mode and are unaffected.
+
+  The rule is a pure per-line comparison made when the marker is first scanned,
+  so it costs no lookahead and no re-parse while streaming.
 - `a11y: true` — opt-in accessibility markup that deviates from strict GFM
   byte-output: wraps task-list checkboxes in a `<label>` (screen-reader
   association) and adds `scope="col"` to table headers. Off by default so
@@ -664,6 +705,15 @@ When to enable each flag:
 - `htmlAllowlist` / `dropHtmlTags` — render a **safe subset of raw HTML** (e.g.
   `<br>`, `<sub>`, `<sup>`) natively without `unsafeHtml`, drop specific tags, and
   drop HTML comments. See [Safe raw HTML](#safe-raw-html).
+- `blockHtml: true` — extend that sanitizer to **block-level** raw HTML, so a
+  `<details><summary>…</summary>…</details>` block renders as real elements
+  instead of an escaped code block. Needs one of the two lists above to be set;
+  `<script>`/`<pre>`/`<style>`/`<textarea>` blocks stay escaped. See
+  [Block-level raw HTML](#block-level-raw-html-blockhtml).
+- `allowSchemes: ["file"]` — un-block a URL scheme brookmd blocks by default,
+  for privileged hosts (Electron, extensions) that intercept link clicks instead
+  of navigating. Script-executing schemes can never be re-enabled. See
+  [Un-blocking a scheme](#un-blocking-a-scheme--allowschemes).
 
 **Footnotes** (`gfmFootnotes`) work in streaming with one honest caveat: a
 `[^1]` reference renders speculatively the moment it's seen (committed blocks
@@ -763,8 +813,9 @@ attributes (with `class`→`className` and `style` as an object) plus `children`
 **Block-kind** keys (`CodeBlock`, `Mermaid`, `MathBlock`, `Alert`, `Paragraph`,
 `Heading`, `List`, `Blockquote`, `Table`, `Rule`, `Html`) replace the entire
 block. The component receives [`BlockComponentProps`](#types): `{ block, html,
-open, speculative }`, plus `text`/`language` for code/math blocks (the alert
-type is at `block.kind.data.kind`).
+open, speculative }`, plus `text`/`language` for code/math blocks — and `meta`,
+the rest of a fence's info string (```` ```ts title="src/main.ts" ````), for a
+filename header (the alert type is at `block.kind.data.kind`).
 
 > **One map, two prop contracts — the single biggest footgun.** The keys above
 > are looked up by TWO dispatchers. The block-kind dispatcher passes
@@ -866,7 +917,7 @@ byte-identical, so non-users pay nothing.
 |------|-------------------|------|-----|
 | `Table` | `{ headers, rows, aligns }`, cells `{ text, html }` | `props.table` | sort / filter / transpose / CSV / chart |
 | `Heading` | `{ level, text, id }` | `props.heading` | table of contents with anchors |
-| `CodeBlock` | `{ lang, code }` | `props.code` | decoded source (copy / run) |
+| `CodeBlock` | `{ lang, meta?, code }` | `props.code` | decoded source (copy / run) |
 | `MathBlock` | `{ latex }` | `props.math` | LaTeX source (re-render) |
 | `List` | `{ ordered, start }` | `props.list` | ordered-list numbering |
 
@@ -1004,11 +1055,77 @@ new BrookClient({ config: { htmlAllowlist: [] } });
   text stays as inert text).
 - Every rendered tag's **attributes are sanitized**: `on*` handlers and `style`
   (a CSS beacon / clickjacking vector) are dropped, and dangerous URL schemes
-  (`javascript:`, …, including multi-encoded) become `#`.
-- **Scope:** *inline* raw HTML. Block-level raw HTML stays escaped for now (use
-  `unsafeHtml` **without** the sanitizer to render block HTML — when the sanitizer
-  is engaged, block HTML stays escaped even if `unsafeHtml` is also on). Tag
-  matching is case-insensitive.
+  (`javascript:`, …, including multi-encoded) become `#` — in `href`, `src`,
+  `srcset`, `poster`, `cite`, `action`, `data`, `longdesc` and `background`.
+- A further set of **DOM-hazard attributes is dropped outright** (case-insensitive)
+  — they neither execute nor carry a URL, but each lets authored markup reach
+  past the text it should be:
+  `srcdoc` (inline document injection), `is` (customized-built-in upgrade),
+  `autofocus` / `contenteditable` (focus-steal, UI spoof), `id` / `name` (DOM
+  clobbering — an element shadowing `document.getElementById` or a global),
+  `slot` / `part` / `exportparts` (shadow-DOM injection), `form`, `formaction`,
+  `formenctype`, `formmethod`, `formnovalidate`, `formtarget` (form hijack),
+  `xmlns` / `xlink:*` (namespace escape hatch), and `ping` (tracking beacon).
+  Some are inert *today* only because the tag that gives them meaning is already
+  in the dangerous set — they are dropped anyway so the policy never depends on
+  that coincidence. `class`, `title`, `alt`, `target`, `rel`, `data-*` and
+  `aria-*` are unaffected.
+- **This applies to raw HTML only.** [Component tags](#component-tags) stay
+  permissive: their attributes become framework *props* on `components[tag]`, so
+  `<Tab id="x">` keeps `id` — the consumer's component decides whether it ever
+  reaches the DOM. `on*`, `style` and dangerous URL schemes are filtered there too.
+- **Scope:** *inline* raw HTML by default. Block-level raw HTML stays escaped
+  unless you also set `blockHtml` (below). Tag matching is case-insensitive.
+
+#### Block-level raw HTML (`blockHtml`)
+
+A model that emits a disclosure widget on its own lines —
+
+```html
+<details>
+<summary>Sources</summary>
+Three filings and a transcript.
+</details>
+```
+
+— produces an *HTML block*, not inline HTML, so the sanitizer above leaves it
+escaped. Opt in with `blockHtml` and it renders as real elements:
+
+```ts
+new BrookClient({ config: { htmlAllowlist: [], blockHtml: true } });
+// or restrict it:
+new BrookClient({ config: { htmlAllowlist: ["details", "summary"], blockHtml: true } });
+```
+
+- **Only meaningful with the sanitizer engaged.** `blockHtml` on its own does
+  nothing; it extends `htmlAllowlist` / `dropHtmlTags` to block level. Default
+  `false`, so existing sanitizer users keep escaped block HTML until they opt in.
+- **Same policy, no exceptions.** Tags go through the same allow / drop /
+  non-overridable-dangerous decision and the same hardened attribute policy as
+  inline raw HTML — a block-level `<div onclick=… id=… srcdoc=…>` renders as a
+  bare `<div>`.
+- **Scope: CommonMark HTML block types 6 and 7** — a known block-level tag
+  (`<details>`, `<div>`, `<table>`, `<section>`, …) or any other complete tag
+  alone on its line. **Types 1–5 stay escaped/dropped**, as with the flag off:
+  type 1 is the raw-text family (`<script>`, `<pre>`, `<style>`, `<textarea>`),
+  where a browser reads everything after the opening tag as unparsed text — so a
+  *speculative* close mid-stream is an mXSS vector — and types 2–5 (comments,
+  processing instructions, CDATA, declarations) carry no renderable element at
+  all. A block `<script>` is escaped in every configuration, including with
+  `script` explicitly allowlisted and `unsafeHtml` also on.
+- **Streaming: speculative closers.** While the block is still arriving, every
+  still-open element gets a closer appended, so the HTML you have received *so
+  far* is always a complete tree — `<div>\n<b>bol` renders as
+  `<div><b>bol</b></div>`, and the closers simply stop being speculative when the
+  author's own `</b></div>` lands (the emitted bytes don't change). A half-arrived
+  tag (`<spa`, `<a href="htt`) renders as **nothing** until it completes, the same
+  pending-invisible contract as a streaming markdown link's URL; if the stream
+  ends on one, it settles as escaped text. Mis-nesting is repaired rather than
+  propagated: `<b><i></b>` emits `<b><i></i></b>`, and a close tag matching
+  nothing open is dropped. A type-6/7 block ends at a blank line even with tags
+  open — the closers land there.
+- **Markdown inside the HTML is not parsed** (the body is text + tags). That —
+  full `rehype-raw` semantics — is a later stage.
 
 ### Types
 
@@ -1033,7 +1150,8 @@ interface BlockComponentProps {
   open: boolean;
   speculative: boolean;
   text?: string;      // decoded source — CodeBlock / MathBlock
-  language?: string;  // info string — CodeBlock
+  language?: string;  // info string, first word — CodeBlock
+  meta?: string;      // info string, the rest (`title="src/main.ts"`) — CodeBlock
 }
 ```
 
@@ -1051,14 +1169,35 @@ const html = highlight("const x = 1;", "ts");
 
 ## Coverage
 
-**CommonMark 0.31: 100% (652/652 spec examples)** — every section, including
-the hard ones (nested/loose lists, link reference definitions, link precedence,
-lazy blockquote continuation). Plus GFM extensions: tables, strikethrough, task
-lists, extended autolinks, GitHub alerts (`> [!NOTE]` → styled callouts),
-footnotes (`[^1]` + `[^1]:`), and math (`$…$`, `$$…$$`, `\(…\)`, `\[…\]`).
-Autolinks and alerts are on by default; footnotes and math are opt-in per stream
-(see [Per-stream config](#per-stream-config)). See
-`crates/brookmd-core/tests/{cmark_spec,gfm_spec,footnotes,math}.rs` for runners and floors.
+**CommonMark 0.31: 100% (652/652 spec examples), byte-exact** — every section,
+including the hard ones (nested/loose lists, link reference definitions, link
+precedence, lazy blockquote continuation). Plus GFM extensions, also **24/24
+byte-exact**: tables, strikethrough, task lists, extended autolinks, GitHub
+alerts (`> [!NOTE]` → styled callouts), footnotes (`[^1]` + `[^1]:`), and math
+(`$…$`, `$$…$$`, `\(…\)`, `\[…\]`). Autolinks and alerts are on by default;
+footnotes and math are opt-in per stream (see
+[Per-stream config](#per-stream-config)).
+
+*Byte-exact* means the full output string matches the reference renderer's
+byte-for-byte — not a structurally normalized or whitespace-forgiving compare.
+Both counts are the harnesses' **default** floors (`CMARK_MIN_EXACT=652`,
+`GFM_MIN_EXACT=24`, pinned explicitly in the CI workflows), so a single byte of
+regression fails the build even when the normalized tally stays green.
+
+The only deviations from the reference output are deliberate brookmd choices,
+folded by a documented `canonicalize` step applied to **both** sides before
+comparison — the only transform on the byte-exact path, so it can erase our
+intentional extras but never hide a structural divergence:
+
+| Deliberate difference | Reference emits |
+|---|---|
+| `target="_blank" rel="noopener noreferrer nofollow"` on links (security-only) | no such attrs |
+| `data-lang="…"` on code blocks (alongside `class="language-…"`) | `class` only |
+| HTML5 void elements (`<br>`) | XHTML self-closing (`<br />`) |
+| `style="text-align:…"` on table cells | GFM's deprecated `align="…"` |
+
+See `crates/brookmd-core/tests/{cmark_spec,gfm_spec,footnotes,math}.rs` for the
+runners, the `canonicalize` source, and the floors.
 
 GitHub alerts render to GitHub-compatible markup
 (`<div class="markdown-alert markdown-alert-note">…`), so existing markdown CSS
@@ -1125,17 +1264,61 @@ brookmd is XSS-safe by default — its HTML output is meant to be injected via
 - **Raw HTML is escaped** (the `unsafeHtml: true` config flag disables this;
   **never enable it for untrusted input without a `sanitize` hook**).
 - **Dangerous URL schemes are neutralized** in `<a href>` and `<img src>` —
-  `javascript:`, `vbscript:`, `data:text/html`, `data:text/javascript` become
-  `#`. The check runs on the *decoded* URL and strips characters browsers
-  ignore in the scheme, so obfuscations like `javascript&#58;…`,
-  `javascript\:…`, `&#106;avascript:…`, and embedded tabs/newlines are caught,
-  not just the literal form. (See `crates/brookmd-core/tests/security.rs`.)
+  `javascript:`, `vbscript:`, `data:text/html`, `data:text/javascript` (and
+  `file:`, see below) become `#`. The check runs on the *decoded* URL and strips
+  characters browsers ignore in the scheme, so obfuscations like
+  `javascript&#58;…`, `javascript\:…`, `&#106;avascript:…`, and embedded
+  tabs/newlines are caught, not just the literal form. (See
+  `crates/brookmd-core/tests/security.rs`.)
+- **The opt-in raw-HTML sanitizer removes DOM-hazard attributes.** Beyond `on*`,
+  `style` and URL schemes, [Safe raw HTML](#safe-raw-html) drops `srcdoc`, `is`,
+  `autofocus`, `contenteditable`, `id`/`name` (DOM clobbering), `slot`/`part`/
+  `exportparts`, the `form*` family and `ping` from raw tags — a denylist by
+  *policy*, not one that happens to be safe because some other tag is blocked.
+  brookmd's own generated ids (footnote `fn-N`/`fnref-N`, heading slugs) are
+  emitted by the renderer and never pass through the sanitizer, so they are
+  unaffected. Component-tag props are exempt (see that section).
 - **`htmlToReact` defends in depth**: it drops inline `on*` event-handler
   attributes and runs URL attributes through the same scheme filter. It's
   intended for brookmd's own (already-sanitized) HTML; if you hand it arbitrary
   third-party HTML, these guards are your only line of defense — prefer a
   dedicated HTML sanitizer for genuinely hostile input.
 
+### Un-blocking a scheme — `allowSchemes`
+
+`file:` is blocked by default. It can't execute script, but it has no legitimate
+use in untrusted/LLM markdown, and in a **privileged** host — Electron, a browser
+extension, a page on a `file://` origin — a live `file:` href is a
+local-resource-disclosure / phishing vector. In an ordinary browser tab blocking
+it costs nothing anyway: a page simply **refuses to navigate** to a `file:` URL,
+so the href is inert there either way.
+
+Some hosts genuinely need it. A coding-agent UI whose model links to local paths
+wants the href present so it can **intercept the click** and open the file in an
+editor or preview pane. `allowSchemes` is the opt-in for exactly that:
+
+```ts
+const client = new BrookClient({ config: { allowSchemes: ["file"] } });
+```
+
+- Takes **bare scheme names, no colon** (`["file"]`), matched
+  case-insensitively.
+- It **never restricts** anything — this is not a general allowlist. Schemes
+  outside the built-in blocklist (`vscode:`, `ftp:`, `mailto:`, …) already render
+  today and are unaffected by this setting.
+- The **script-executing tier is non-overridable**: `javascript:`, `vbscript:`,
+  `data:text/html`, `data:text/javascript`, and the scriptable `data:` media
+  types (`data:image/svg`, `data:application/xhtml`, `data:text/xml`, …) stay
+  blocked no matter what you list. Naming one is a silent no-op — the same rule
+  as `htmlAllowlist`, where allowlisting `<script>` still cannot re-enable it.
+- Applies uniformly to links, URI autolinks, images, and sanitized URL
+  attributes.
+
+Turning it on moves the risk to you: **intercept link clicks rather than letting
+navigation happen**, and treat the path as untrusted input at the point you act
+on it. In a privileged host, whether a model-authored `file:///…` is allowed to
+reach a real file is the embedder's decision, not brookmd's.
+
 ### Rendering untrusted / LLM HTML safely
 
 If you enable `unsafeHtml` to render HTML from an untrusted source (e.g. an LLM

package/dist/block-props.js

@@ -38,8 +38,9 @@ function blockProps(block) {
   if (block.kind.type === "CodeBlock") {
     props.text = data?.code ?? decodeCodeText(block.html);
     props.language = data?.lang ?? "";
+    if (typeof data?.meta === "string") props.meta = data.meta;
     if (typeof data?.code === "string") {
-      props.code = { lang: data.lang ?? null, code: data.code };
+      props.code = { lang: data.lang ?? null, meta: data.meta, code: data.code };
     }
   } else if (block.kind.type === "MathBlock") {
     props.text = data?.latex ?? decodeMathText(block.html);