brookmd 0.29.1 → 0.30.0

package/dist/dom.d.ts

@@ -1,5 +1,5 @@
 import type { BrookClient } from "./client.js";
-import type { Block, BlockComponentProps, Decorator, RenderMetricsHook, UrlTransform } from "./types-core.js";
+import type { Block, BlockComponentProps, Decorator, LinkClickInfo, RenderMetricsHook, UrlTransform } from "./types-core.js";
 /**
  * Framework-neutral DOM renderer for a {@link BrookClient}. Mounts the streaming
  * document into a container and keeps it in sync via direct DOM mutation,
@@ -37,6 +37,7 @@ export interface MountHandle {
      */
     openBlockId(): number | null;
 }
+export type { LinkClickInfo };
 export type DomBlockComponent = (props: BlockComponentProps) => HTMLElement | string;
 /** Override map: capitalized block-kind / component-tag keys only. */
 export type DomComponents = Record<string, DomBlockComponent>;
@@ -72,9 +73,19 @@ export interface MountOptions {
      * An open block keeps a frozen prefix and re-tokenizes only its tail on each
      * patch, so this stays linear in the block's size. The settled markup is
      * byte-identical either way — only the tail's colours are provisional, and
-     * they may shift as bytes arrive. Set `false` for the pre-0.27 behaviour.
+     * they may shift as bytes arrive.
+     *
+     * - `true` / omitted — `"wavefront"`.
+     * - `"wavefront"` — the frozen prefix is coloured; the speculative tail (in
+     *   practice the line being typed) renders as plain text until its line
+     *   completes. The tail is one text node updated through its character data,
+     *   which is what keeps the option's cost at the DOM near zero.
+     * - `"eager"` — colour the tail on every patch too, by rebuilding its span
+     *   markup each time. Sub-line colour latency, ~all of the option's
+     *   style/layout cost.
+     * - `false` — the pre-0.27 behaviour: plain body until the fence closes.
      */
-    streamingHighlight?: boolean;
+    streamingHighlight?: boolean | "wavefront" | "eager";
     /** Coalesce patches into one DOM write per animation frame. Default true. */
     batch?: boolean;
     /**
@@ -107,6 +118,17 @@ export interface MountOptions {
      * scheme. O(1) per attribute.
      */
     urlTransform?: UrlTransform;
+    /**
+     * Called when a rendered link is clicked (parity with the React `onLinkClick`
+     * prop). Exactly ONE `click` listener is added to the renderer root and the
+     * anchor is resolved from the event target — never a listener per anchor, so
+     * this costs nothing per block and the streaming path is untouched. The
+     * listener is removed by {@link MountHandle.destroy}.
+     *
+     * `event.preventDefault()` cancels the navigation. A still-streaming anchor
+     * (`data-brook-pending`, no href yet) is never reported.
+     */
+    onLinkClick?: (event: MouseEvent, link: LinkClickInfo) => void;
     /** Appended to the root's `className` (the `brook-md` class is always present). */
     className?: string;
     /** Set on the root element. */

package/dist/dom.js

@@ -1,7 +1,7 @@
 import { highlightDeferred } from "./hi-defer.js";
 import { createInc, incHighlight, incSeed } from "./hi-inc.js";
 import { morph } from "./morph.js";
-import { newIncCode, paintIncCode, spliceHtml, spliceKeep } from "./splice.js";
+import { incView, newIncCode, paintIncCode, spliceHtml, spliceKeep } from "./splice.js";
 import { blockProps, extractLang } from "./block-props.js";
 import { decorateSegments } from "./decorate.js";
 import { safeUrl } from "./url-safety.js";
@@ -28,18 +28,26 @@ const INTRINSIC_PX = {
   Html: 80,
   Component: 120
 };
+function linkFromEvent(target, root) {
+  const el = target;
+  if (!el || typeof el.closest !== "function") return null;
+  const a = el.closest("a[href]");
+  if (!a || !root.contains(a) || a.hasAttribute("data-brook-pending")) return null;
+  return a;
+}
 function mountBrookMarkdown(client, container, options = {}) {
   if (typeof document === "undefined") {
     throw new Error("mountBrookMarkdown is browser-only; call it after the DOM exists.");
   }
   const components = options.components && Object.keys(options.components).length > 0 ? options.components : void 0;
-  const { sanitize, virtualize, stickToBottom, onRenderMetrics } = options;
+  const { sanitize, virtualize, stickToBottom, onRenderMetrics, onLinkClick } = options;
   const decorators = options.decorators && options.decorators.length > 0 ? options.decorators : void 0;
   const urlTransform = options.urlTransform;
   const hasInlineTransforms = !!decorators || !!urlTransform;
   const hasPerf = typeof performance !== "undefined";
   const highlightCode = options.highlightCode !== false && !components?.CodeBlock;
   const streamingHighlight = options.streamingHighlight !== false;
+  const tailMode = options.streamingHighlight === "eager" ? "eager" : "wavefront";
   const batch = options.batch !== false && typeof requestAnimationFrame === "function";
   const morphOpenBlocks = options.morphOpenBlocks === true;
   const fullRebuild = options.__fullRebuild === true;
@@ -58,6 +66,16 @@ function mountBrookMarkdown(client, container, options = {}) {
     anchor.style.scrollSnapAlign = "end";
     root.appendChild(anchor);
   }
+  const linkClickListener = onLinkClick ? (ev) => {
+    const a = linkFromEvent(ev.target, root);
+    if (!a) return;
+    onLinkClick(ev, {
+      href: a.getAttribute("href") ?? "",
+      text: a.textContent ?? "",
+      element: a
+    });
+  } : null;
+  if (linkClickListener) root.addEventListener("click", linkClickListener);
   const mounted = /* @__PURE__ */ new Map();
   let order = [];
   let dead = false;
@@ -510,10 +528,11 @@ function mountBrookMarkdown(client, container, options = {}) {
       }
       if (inc !== void 0) openMarkup = incHighlight(inc, codeText(b));
     }
+    const openView = openMarkup === null || mb.inc === void 0 ? openMarkup : incView(mb.inc, openMarkup, tailMode);
     const seed = !b.open && mb.inc !== void 0 ? incSeed(mb.inc, text, lang) : void 0;
     const run = text ? highlightDeferred(text, lang, seed) : null;
     if (!b.open) mb.inc = void 0;
-    const highlighted = openMarkup ?? (run ? run.html : null);
+    const highlighted = openView ?? (run ? run.html : null);
     const block = document.createElement("div");
     block.className = "brook-code-block" + (b.open ? " brook-streaming" : "");
     const header = document.createElement("div");
@@ -572,9 +591,9 @@ function mountBrookMarkdown(client, container, options = {}) {
     pre.setAttribute("role", "region");
     pre.setAttribute("aria-label", `${lang} code`);
     const code = document.createElement("code");
-    const ic = newIncCode(code, lang, st);
+    const ic = newIncCode(code, lang, st, tailMode);
     if (paintIncCode(ic, st, markup)) mb.codeInc = ic;
-    else code.innerHTML = markup;
+    else code.innerHTML = incView(st, markup, tailMode);
     pre.appendChild(code);
     return pre;
   }
@@ -680,6 +699,7 @@ function mountBrookMarkdown(client, container, options = {}) {
         frame = 0;
       }
       unsubscribe();
+      if (linkClickListener) root.removeEventListener("click", linkClickListener);
       for (const mb of mounted.values()) {
         if (mb.highlight) {
           mb.highlight.cancel();

package/dist/element.d.ts

@@ -1,3 +1,4 @@
+import { type LinkClickInfo } from "./dom.js";
 /**
  * `<brook-markdown>` custom element — thin lifecycle glue over
  * {@link mountBrookMarkdown}. It owns no diffing: connect mounts the DOM
@@ -17,4 +18,6 @@
  * browser code.
  */
 export declare function parseTriBool(value: string | null): boolean | undefined;
+/** The `onLinkClick` handler shape, mirroring `MountOptions.onLinkClick`. */
+export type LinkClickHandler = (event: MouseEvent, link: LinkClickInfo) => void;
 export declare function defineBrookMarkdown(tag?: string): void;

package/dist/element.js

@@ -23,17 +23,19 @@ const CONFIG_ATTRS = [
   "block-html",
   "retain-committed-html"
 ];
+const MOUNT_ATTRS = ["stick-to-bottom", "virtualize"];
 function defineBrookMarkdown(tag = "brook-markdown") {
   if (typeof customElements === "undefined") return;
   if (customElements.get(tag)) return;
   class BrookMarkdownElement extends HTMLElement {
     static get observedAttributes() {
-      return ["markdown", "src", "component-tags", "allow-schemes", ...CONFIG_ATTRS];
+      return ["markdown", "src", "component-tags", "allow-schemes", ...MOUNT_ATTRS, ...CONFIG_ATTRS];
     }
     #client = null;
     #ownsClient = false;
     #components = void 0;
     #sanitize = void 0;
+    #onLinkClick = void 0;
     #handle = null;
     #connected = false;
     // In-flight `src` fetch supersession. A self-owned client is REUSED across
@@ -71,6 +73,14 @@ function defineBrookMarkdown(tag = "brook-markdown") {
       this.#sanitize = value;
       if (this.#connected) this.#remount();
     }
+    get onLinkClick() {
+      return this.#onLinkClick;
+    }
+    set onLinkClick(value) {
+      if (value === this.#onLinkClick) return;
+      this.#onLinkClick = value;
+      if (this.#connected) this.#remount();
+    }
     // --- Self-owned-client methods -------------------------------------------
     append(chunk) {
       this.#cancelSrcStream();
@@ -95,6 +105,7 @@ function defineBrookMarkdown(tag = "brook-markdown") {
       this.#upgradeProperty("client");
       this.#upgradeProperty("components");
       this.#upgradeProperty("sanitize");
+      this.#upgradeProperty("onLinkClick");
       this.#mountIfReady();
       if (!this.#client || this.#ownsClient) {
         this.#resolveInitialContent();
@@ -109,6 +120,10 @@ function defineBrookMarkdown(tag = "brook-markdown") {
         }
         return;
       }
+      if (MOUNT_ATTRS.includes(name)) {
+        this.#remount();
+        return;
+      }
       if (this.#client && !this.#ownsClient) {
         console.warn(
           "<brook-markdown>: config attributes are ignored while a caller-owned `client` is set (ParserConfig is immutable per stream)."
@@ -194,7 +209,12 @@ function defineBrookMarkdown(tag = "brook-markdown") {
       if (!this.#connected || !this.#client || this.#handle) return;
       this.#handle = mountBrookMarkdown(this.#client, this, {
         components: this.#components,
-        sanitize: this.#sanitize
+        sanitize: this.#sanitize,
+        onLinkClick: this.#onLinkClick,
+        // Renderer options read fresh on every mount (MOUNT_ATTRS remounts on a
+        // change); `undefined` = absent = the renderer's own default.
+        stickToBottom: parseTriBool(this.getAttribute("stick-to-bottom")),
+        virtualize: parseTriBool(this.getAttribute("virtualize"))
       });
     }
     // Destroy the current mount and remount against the current client+options.

package/dist/hi-inc.d.ts

@@ -49,6 +49,19 @@ export interface OpenerScanState {
 export interface IncState {
     /** The language key this state's tables were chosen for. */
     readonly lang: string;
+    /** The unbounded openers of `lang` — resolved once, at {@link createInc}. */
+    readonly openers: Opener[];
+    /**
+     * May this state freeze a prefix at all?
+     *
+     * False for a language added through `registerLanguage`: the checkpoint rule
+     * is derived from knowing which of a table's forms can run past a newline, and
+     * a caller-supplied table does not say. Such a block is re-tokenized from the
+     * top on each patch (the {@link CAP} bound still applies) and freezes nothing,
+     * which is the one setting that is safe for ANY pattern list — with `c` at 0
+     * there is no frozen byte to be wrong, and the close-time run is unseeded.
+     */
+    readonly freeze: boolean;
     /** Settled through here: `[0, c)` of the source will never re-tokenize. */
     c: number;
     /** Markup for `[0, c)`. Always a byte-prefix of the block's final markup. */

package/dist/hi-inc.js

@@ -1,4 +1,4 @@
-import { escapeHtml, stepHighlight } from "./hi.js";
+import { escapeHtml, hasLang, isRegisteredLang, stepHighlight } from "./hi.js";
 const GAP = 3;
 const CAP = 8192;
 const CLIFF = 5e4;
@@ -43,6 +43,8 @@ const CSS_OPENERS = [
   { re: /"/y, cls: "str", end: '"', pred: { k: "char", ch: '"' } },
   { re: /'/y, cls: "str", end: "'", pred: { k: "char", ch: "'" } }
 ];
+const C_OPENERS = [BLOCK_COMMENT];
+const NO_OPENERS = [];
 const OPENERS = {
   js: JS_OPENERS,
   javascript: JS_OPENERS,
@@ -62,14 +64,34 @@ const OPENERS = {
   sql: SQL_OPENERS,
   html: HTML_OPENERS,
   xml: HTML_OPENERS,
-  css: CSS_OPENERS
+  css: CSS_OPENERS,
+  java: C_OPENERS,
+  c: C_OPENERS,
+  cpp: C_OPENERS,
+  "c++": C_OPENERS,
+  cs: C_OPENERS,
+  csharp: C_OPENERS,
+  swift: C_OPENERS,
+  kt: C_OPENERS,
+  kotlin: C_OPENERS,
+  php: C_OPENERS,
+  rb: NO_OPENERS,
+  ruby: NO_OPENERS,
+  yaml: NO_OPENERS,
+  yml: NO_OPENERS,
+  toml: NO_OPENERS,
+  diff: NO_OPENERS,
+  dockerfile: NO_OPENERS
 };
 const GT_CHECKPOINT = /* @__PURE__ */ new Set(["html", "xml"]);
 function createInc(lang) {
   const key = lang.toLowerCase();
-  if (!Object.prototype.hasOwnProperty.call(OPENERS, key)) return null;
+  const known = Object.prototype.hasOwnProperty.call(OPENERS, key) && !isRegisteredLang(key);
+  if (!known && !hasLang(key)) return null;
   return {
     lang: key,
+    openers: known ? OPENERS[key] : NO_OPENERS,
+    freeze: known,
     c: 0,
     frozenHtml: "",
     frozenRev: 0,
@@ -191,7 +213,7 @@ function plainTail(st, text) {
   return st.plain;
 }
 function rescan(st, text) {
-  const openers = OPENERS[st.lang];
+  const openers = st.openers;
   const gt = GT_CHECKPOINT.has(st.lang);
   const limit = text.length - GAP;
   let cp = -1;
@@ -201,6 +223,7 @@ function rescan(st, text) {
   let liveLen = 0;
   const sink = (cls, start, end, outLen) => {
     if (liveAt >= 0) return;
+    if (!st.freeze) return;
     for (let i = 0; i < openers.length; i++) {
       const op = openers[i];
       op.re.lastIndex = start;

package/dist/hi.d.ts

@@ -1,13 +1,27 @@
 /**
- * In-house syntax highlighter. Native RegExp only — no Shiki, no Prism, no
- * Highlight.js. Covers the languages an LLM typically emits:
- * js/ts/tsx/jsx, rust, python, go, bash, json, html, css, sql. Unknown
- * languages fall through to plain escaped text. ~6KB minified.
+ * In-house syntax highlighter. Native RegExp only. Covers the languages an LLM
+ * typically emits: js/ts/tsx/jsx, rust, python, go, bash, json, html, css, sql,
+ * yaml, toml, diff, java, c/c++, c#, php, ruby, swift, kotlin and dockerfile.
+ * {@link registerLanguage} adds more at runtime; anything still unknown falls
+ * through to plain escaped text.
  *
  * Highlighting is per-block, runs once when the block closes. We never
  * highlight an open (streaming) block, which avoids re-highlighting the same
  * code on every chunk — the main perf win for streaming code.
  */
+/** @internal Test-only: the built-in languages, without registered additions. */
+export declare function __builtinLangs(): string[];
+/** @internal Whether `lang` has a tokenizer table (built-in or registered). */
+/**
+ * Whether `lang` currently resolves to a table supplied through
+ * {@link registerLanguage} — including a built-in name the caller replaced. The
+ * streaming highlighter asks this so a replaced built-in loses the frozen-prefix
+ * mode that was derived from the ORIGINAL table's forms.
+ */
+export declare function isRegisteredLang(lang: string): boolean;
+/** @internal Test-only: restore the built-in tables and forget registrations. */
+export declare function __resetLanguages(): void;
+export declare function hasLang(lang: string): boolean;
 export declare function escapeHtml(s: string): string;
 /**
  * The resumable tokenizer's cursor: `pos` is the next source index to consume,
@@ -50,4 +64,48 @@ export type TokenSink = (cls: string, start: number, end: number, outLen: number
  */
 export declare function stepHighlight(code: string, lang: string, state: HighlightState, chars: number, sink?: TokenSink): boolean;
 export declare function highlight(code: string, lang: string): string;
+/** A language table for {@link registerLanguage}. */
+export interface LanguageDef {
+    /**
+     * Ordered `[token class, sticky regex]` pairs. At each cursor position the
+     * FIRST pattern that matches wins, so put the longer forms first. Every regex
+     * must carry the `y` flag; it is matched against the whole source with
+     * `lastIndex` at the cursor, so `^`/`$` (with `m`) and lookaheads work, and
+     * `\b` sees the real neighbouring characters.
+     */
+    pats: Array<[token: string, re: RegExp]>;
+    /** Words an `ident` token is promoted to `kw` for. Stored as a `Set`. */
+    kw?: Iterable<string>;
+}
+/**
+ * Teach {@link highlight} a language, under one name or several aliases.
+ *
+ *     registerLanguage(["hcl", "tf"], {
+ *       pats: [
+ *         ["com", /#.+/y],
+ *         ["str", /"(?:\\.|[^"\\\n])*"/y],
+ *         ["num", /\b\d+(?:\.\d+)?/y],
+ *         ["ident", /\w+/y],
+ *         ["pun", /[=[\]{}(),.]/y],
+ *         ["ws", /\s+/y],
+ *       ],
+ *       kw: ["resource", "variable", "module", "output", "true", "false"],
+ *     });
+ *
+ * Names are lower-cased, and registering a name that already exists REPLACES
+ * its table — including a built-in one, which is how a caller retunes `yaml` or
+ * `json` rather than living with this module's taste.
+ *
+ * Throws a `TypeError`, naming the offending pattern index, for a regex that is
+ * not sticky or a token class that has no style.
+ *
+ * A registered language highlights exactly like a built-in one when its block
+ * closes. While the block is still STREAMING it is re-tokenized from the top on
+ * each patch instead of growing a frozen prefix: the frozen-prefix rule needs to
+ * know which of a table's forms can run past a newline (a block comment, a
+ * multi-line string), and a caller-supplied table does not say. The size cap in
+ * the streaming path bounds that work; nothing about the settled markup differs.
+ */
+export declare function registerLanguage(names: string | string[], def_: LanguageDef): void;
+/** Every language {@link highlight} knows, built-in and registered alike. */
 export declare function supportedLangs(): string[];