brookmd 0.22.0

package/dist/decorate.d.ts

@@ -0,0 +1,24 @@
+import type { Decorator } from "./types-core.js";
+/** Ancestor tags inside which decoration is skipped by default. */
+export declare const DEFAULT_SKIP: readonly string[];
+/** A run of the original text, or one matched span the caller turns into a node. */
+export type DecorateSegment = {
+    type: "text";
+    text: string;
+} | {
+    type: "match";
+    decorator: Decorator;
+    matchText: string;
+    groups: string[];
+};
+/**
+ * Split one inline text node's string into segments per the active decorators.
+ * Decorators apply in order; each one only re-scans the still-TEXT segments left
+ * by the previous ones (so a match is never decorated twice). `ancestors` is the
+ * chain of enclosing tag names — a decorator whose `skipInside` (default
+ * {@link DEFAULT_SKIP}) intersects it is not applied here.
+ *
+ * Returns `null` when nothing matched at all, so the caller can take the
+ * zero-allocation fast path of emitting the original text node unchanged.
+ */
+export declare function decorateSegments(text: string, decorators: Decorator[], ancestors: string[]): DecorateSegment[] | null;

package/dist/decorate.js

@@ -0,0 +1,71 @@
+const DEFAULT_SKIP = ["a", "code", "pre", "kbd"];
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function toGlobalRegExp(match) {
+  if (typeof match === "string") return new RegExp(escapeRegExp(match), "g");
+  let flags = match.flags.replace("y", "");
+  if (!flags.includes("g")) flags += "g";
+  return new RegExp(match.source, flags);
+}
+function skippedByAncestor(ancestors, skip) {
+  for (let i = 0; i < ancestors.length; i++) {
+    const a = ancestors[i].toLowerCase();
+    for (let j = 0; j < skip.length; j++) {
+      if (a === skip[j].toLowerCase()) return true;
+    }
+  }
+  return false;
+}
+function splitOne(text, dec, out) {
+  const re = toGlobalRegExp(dec.match);
+  let last = 0;
+  let matched = false;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const matchText = m[0];
+    if (matchText.length === 0) {
+      re.lastIndex++;
+      continue;
+    }
+    matched = true;
+    if (m.index > last) out.push({ type: "text", text: text.slice(last, m.index) });
+    const groups = [];
+    for (let i = 1; i < m.length; i++) groups.push(m[i] ?? "");
+    out.push({ type: "match", decorator: dec, matchText, groups });
+    last = m.index + matchText.length;
+  }
+  if (!matched) return false;
+  if (last < text.length) out.push({ type: "text", text: text.slice(last) });
+  return true;
+}
+function decorateSegments(text, decorators, ancestors) {
+  let segments = null;
+  for (let d = 0; d < decorators.length; d++) {
+    const dec = decorators[d];
+    if (skippedByAncestor(ancestors, dec.skipInside ?? DEFAULT_SKIP)) continue;
+    const source = segments ?? [{ type: "text", text }];
+    let changedThisDecorator = false;
+    const next = [];
+    for (let i = 0; i < source.length; i++) {
+      const seg = source[i];
+      if (seg.type !== "text") {
+        next.push(seg);
+        continue;
+      }
+      const before = next.length;
+      if (splitOne(seg.text, dec, next)) {
+        changedThisDecorator = true;
+      } else {
+        next.length = before;
+        next.push(seg);
+      }
+    }
+    if (changedThisDecorator) segments = next;
+  }
+  return segments;
+}
+export {
+  DEFAULT_SKIP,
+  decorateSegments
+};

package/dist/dom.d.ts

@@ -0,0 +1,130 @@
+import type { BrookClient } from "./client.js";
+import type { Block, BlockComponentProps, Decorator, 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,
+ * mirroring the JSX renderer's block model: each block is keyed by its stable
+ * parser-assigned id, and a committed block's node is reused untouched on every
+ * later patch (the parity analogue of the JSX renderer's block memo). Only the
+ * streaming tail is rebuilt.
+ *
+ * This is the foundation the Web Component / Vue / Svelte / Solid bindings
+ * build on; it imports only neutral modules and carries no framework dependency.
+ *
+ * ## Custom components
+ *
+ * Pass `components` to override a whole block kind (or a component tag). Keys
+ * are capitalized block-kind names (`CodeBlock`, `Table`, `Mermaid`…) or, for
+ * `Component` blocks, the tag name (e.g. `Thinking`) with `Component` as the
+ * generic fallback. A component receives {@link BlockComponentProps} and returns
+ * an `HTMLElement` or an HTML string. There is no tag-level override path (no
+ * `table`/`a`/`code` keys) — that requires an HTML→tree pass the DOM renderer
+ * doesn't carry.
+ */
+export interface MountHandle {
+    destroy(): void;
+    refresh(): void;
+    /**
+     * The id of the streaming **tail** block — the one block that may re-render on
+     * the next patch (a committed block's node is frozen, so its id never appears
+     * here). Returns `null` when no block is open (idle / fully committed).
+     *
+     * Purely derived from the live snapshot; reading it renders nothing and mutates
+     * nothing. It exists so a fine-grained framework binding (Solid `createMemo`,
+     * Vue `computed`, Svelte `derived`) can narrow a reactive cell to *just the tail*
+     * for its own scheduling/diagnostics — the DOM is already updated by the
+     * renderer's own subscribe loop, so this never changes what is drawn.
+     */
+    openBlockId(): number | null;
+}
+export type DomBlockComponent = (props: BlockComponentProps) => HTMLElement | string;
+/** Override map: capitalized block-kind / component-tag keys only. */
+export type DomComponents = Record<string, DomBlockComponent>;
+export interface MountOptions {
+    components?: DomComponents;
+    /**
+     * Optional HTML sanitizer applied to every generic block's HTML before it is
+     * injected via `innerHTML` — **including the streaming (open/speculative)
+     * tail**. The built-in code/math/mermaid renderers operate on already-escaped
+     * content and are not run through it (same as the JSX renderer). When omitted,
+     * rendering is byte-identical and zero-cost.
+     */
+    sanitize?: (html: string) => string;
+    /**
+     * Skip layout/paint for off-screen *closed* blocks via CSS
+     * `content-visibility: auto` (for very long documents). Off by default.
+     */
+    virtualize?: boolean;
+    /**
+     * Keep a bottom snap target so the view follows the streaming tail. CSS-only:
+     * emits a sentinel with `scroll-snap-align: end`; you add
+     * `scroll-snap-type: y proximity` to your scroll container. Off by default.
+     */
+    stickToBottom?: boolean;
+    /** Use the built-in code highlighter. Default true; suppressed when a
+     *  `components.CodeBlock` override is supplied. */
+    highlightCode?: boolean;
+    /** Coalesce patches into one DOM write per animation frame. Default true. */
+    batch?: boolean;
+    /**
+     * Opt-in (default false). When a generic open/streaming block grows, morph its
+     * existing DOM subtree **in place** toward the new HTML instead of rebuilding
+     * the whole node with `innerHTML`. The browser then only repaints/relayouts
+     * the parts that changed, and focus/text-selection inside the streaming tail
+     * survive a token append. The default path (full rebuild) is byte-identical
+     * and unchanged; this only affects generic blocks rendered via the `innerHTML`
+     * fast path (not code/math/mermaid/component overrides). The morphed subtree is
+     * equivalent to the rebuilt one. */
+    morphOpenBlocks?: boolean;
+    /**
+     * Wrap or replace matched inline **text** while streaming (parity with the
+     * React `decorators` prop). Each {@link Decorator} runs POST-render over the
+     * block's real TEXT nodes via a `TreeWalker` (after `innerHTML`), once per
+     * committed block, honoring `skipInside` (default `a`/`code`/`pre`/`kbd`).
+     *
+     * **Trusted surface.** A decorator's `replace` may return a `Node` or a string;
+     * a returned Node is inserted as-is and is NOT sanitized (a `javascript:` href
+     * on a user-built `<a>` reaches the DOM). Route hrefs through the exported
+     * {@link safeUrl}. Enabling decorators moves a block onto the walk path (off the
+     * `innerHTML`/prefix-append/morph fast paths) — still O(n) per block.
+     */
+    decorators?: Decorator[];
+    /**
+     * Rewrite `href`/`src`/`poster` URLs as blocks render (parity with the React
+     * `urlTransform` prop). The output is re-sanitized
+     * (`safeUrl(urlTransform(safeUrl(v)))`) so it can never introduce a dangerous
+     * scheme. O(1) per attribute.
+     */
+    urlTransform?: UrlTransform;
+    /** Appended to the root's `className` (the `brook-md` class is always present). */
+    className?: string;
+    /** Set on the root element. */
+    id?: string;
+    /** Set on the root element (e.g. `"article"`, `"log"`). */
+    role?: string;
+    /**
+     * Make the root a live region so screen readers announce streamed content.
+     * `"polite"` coalesces rapid updates (does not read every token). Off by default.
+     */
+    ariaLive?: "off" | "polite" | "assertive";
+    /** Live-region atomicity; pair with `ariaLive`. Off by default. */
+    ariaAtomic?: boolean;
+    /**
+     * Optional render-churn probe. Fires once per ACTUAL node build/rebuild of a
+     * block — never for a committed block whose node is reused untouched on a
+     * tail-only patch. The callback gets the block id and a {@link RenderMetrics}
+     * sample (per-block `renderCount`/rebuild count, `speculativeToggleCount`,
+     * `lastRenderMs`, `kind`). Zero overhead when omitted, and advances
+     * `client.getMetrics().rebuildCount`.
+     */
+    onRenderMetrics?: RenderMetricsHook;
+}
+export declare function mountBrookMarkdown(client: BrookClient, container: HTMLElement, options?: MountOptions): MountHandle;
+/**
+ * Derive the streaming tail's block id from an ordered snapshot: the id of the
+ * last block when it is open, else `null`. The open block is always the tail by
+ * construction (the parser only keeps the final block speculative/open), so this
+ * is an O(1) read of the last element — no scan. Shared so the framework
+ * adapters expose the same "what may re-render next" signal as the DOM handle.
+ */
+export declare function tailOpenBlockId(snapshot: readonly Block[]): number | null;