feat(core): emit dev-only pipeline stage timings and surface them in the benchmark

The block-memo path runs four stages per content change (parse →
transform → build → render) and every optimization decision should start
from that split. measureStage() wraps each stage and emits one
performance.measure per execution (ai-markdown:stage:*), so the DevTools
Performance panel picks them up with zero wiring and the BlockMemoCompare
story's new 'Pipeline stages' panel aggregates avg/Σ/count/max per stage.

Design points, each the survivor of a review finding:
- PIPELINE_STAGES tuple is the single source of truth: the union type,
  the emitted names (hoisted table, no per-call allocation), and the
  panel's display order all derive from it — a new stage cannot be
  silently omitted from the display.
- measureStage(stage, fn) is single-callable: the stage name is a typed
  argument and the start/end pairing is unforgettable by construction.
- The ENABLED gate builds on the shared DEV constant plus a ONE-TIME
  capability probe of the exact calls made (options-object measure +
  clearMeasures) — environments with only legacy measure overloads gate
  off permanently instead of paying a swallowed throw per stage per token.
- Entries are cleared from the global User Timing buffer immediately
  after emission: live observers still receive every entry (delivery is
  queued at creation) while the buffer never grows from render work —
  ~4 entries/token in ANY consuming app's dev build, observer or not.
  Buffer readers (console getEntriesByType, late buffered observers) see
  nothing by design; documented in docs/streaming-and-performance.md
  ('Built-in stage timing') together with the always-on-in-dev tradeoff.
- Production builds fold ENABLED to false; unbundled Node SSR pays one
  boolean per stage.

Story side: useRenderProfiler gains observeStages (page-wide measures —
enabled ONLY on the block-memo side per page to keep attribution honest;
IsolatedSide enables it for memo mode).

Author: AIEPhoenix

docs/streaming-and-performance.md

@@ -205,6 +205,40 @@ If profiling shows `<AIMarkdown>` as the bottleneck:
 2. Try `blockMemoEnabled: false` to isolate whether the issue is in memoization or upstream.
 3. Profile with React DevTools — a tree with most blocks under "Did not render" is healthy.
 
+### Built-in stage timing (dev builds only)
+
+In development builds, the block-memo render path emits one
+[`performance.measure`](https://developer.mozilla.org/docs/Web/API/Performance/measure)
+entry per pipeline stage per content change, named:
+
+```
+ai-markdown:stage:parse      # unified.parse over the full document
+ai-markdown:stage:transform  # remark/rehype transformer run
+ai-markdown:stage:build      # block-plan construction
+ai-markdown:stage:render     # per-block render with cache lookup
+```
+
+This is how to answer "which stage eats the budget" without guessing —
+the numbers map 1:1 onto the (1)/(2)/(3) split above. Two supported ways
+to read them:
+
+- **DevTools Performance panel**: record a session; the measures appear in
+  the User Timing track. No wiring needed — emission is always on in dev,
+  which is a deliberate choice traded against a few `performance.*` calls
+  per token.
+- **A live `PerformanceObserver`** for `entryTypes: ['measure']`, filtering
+  by the `ai-markdown:stage:` prefix (the built-in Storybook benchmark's
+  "Pipeline stages" panel does exactly this).
+
+Delivery semantics to know before wiring your own reader: each entry is
+**cleared from the global User Timing buffer immediately after emission**,
+so the buffer never grows from render work. Already-registered observers
+still receive every entry (delivery is queued at creation), but
+`performance.getEntriesByType('measure')` from the console and
+late-attached `buffered: true` observers will see nothing — attach your
+observer before streaming starts. Production builds emit nothing and pay
+one boolean check per stage.
+
 ### Validating output equivalence
 
 If you suspect `blockMemoEnabled: true` is producing different output than `false`, the library's test suite includes a `byteEquivalence.test.tsx` harness that asserts byte-identical HTML across every plugin permutation. Failures should be reported as bugs.

packages/core/src/components/MarkdownContent.tsx

@@ -65,6 +65,7 @@ import remarkSmartypants from 'remark-smartypants';
 import remarkPangu from 'remark-pangu';
 import remarkRemoveComments from 'remark-remove-comments';
 import { buildBlocks, createCache, renderBlocksWithCache, type Cache, type PostOptions } from './blockMemo';
+import { measureStage } from './devStageTimings';
 import { useAIMarkdownRenderState } from '../context';
 import {
   AIMarkdownCustomComponents,
@@ -440,12 +441,17 @@ const BlockMemoizedRenderer = memo(
         : {
             ...remarkRehypeOptions,
           };
-      return parseStage({
-        children: augmented,
-        remarkPlugins,
-        rehypePlugins,
-        remarkRehypeOptions: mergedRemarkRehypeOptions as RemarkRehypeOptions,
-      });
+      // Dev-only stage telemetry (`ai-markdown:stage:*` performance
+      // measures; no-op in production). Wraps only the stage call — the
+      // surrounding option assembly is trivial.
+      return measureStage('parse', () =>
+        parseStage({
+          children: augmented,
+          remarkPlugins,
+          rehypePlugins,
+          remarkRehypeOptions: mergedRemarkRehypeOptions as RemarkRehypeOptions,
+        })
+      );
     }, [
       content,
       targetPhantoms,
@@ -456,11 +462,14 @@ const BlockMemoizedRenderer = memo(
       preserveForBodyHarvest,
       documentId,
     ]);
-    const hast = useMemo(() => transformStage(parsed), [parsed]);
+    const hast = useMemo(() => measureStage('transform', () => transformStage(parsed)), [parsed]);
 
     // Cut hast into per-block units indexed back to mdast for cache identity,
     // and compute the document-wide ctx digest for cross-block invalidation.
-    const built = useMemo(() => buildBlocks(parsed.mdast, hast, content ?? ''), [parsed.mdast, hast, content]);
+    const built = useMemo(
+      () => measureStage('build', () => buildBlocks(parsed.mdast, hast, content ?? '')),
+      [parsed.mdast, hast, content]
+    );
 
     const postOptions = useMemo<PostOptions>(
       () => ({
@@ -613,7 +622,12 @@ const BlockMemoizedRenderer = memo(
     }, [parsed, ownLabels, registry, targetPhantoms, sym, hast, clobberPrefix, urlTransform]);
 
     // Intentional cache memoization via cacheRef; see G3 comment above.
-    const rendered = renderBlocksWithCache(cacheRef, built.plan, built.globalCtx, postOptions);
+    // Unlike the three memoized stages above, this runs on EVERY render —
+    // its 'render' measures therefore include the cheap all-cache-hit
+    // re-renders, which is the honest shape of what block-memo saves.
+    const rendered = measureStage('render', () =>
+      renderBlocksWithCache(cacheRef, built.plan, built.globalCtx, postOptions)
+    );
 
     // Cross-chunk URL sanitization policy — read by `CrossChunkLink` and
     // `CrossChunkImage` at render time to apply the same two-gate pipeline

packages/core/src/components/devStageTimings.ts

@@ -0,0 +1,94 @@
+/**
+ * Dev-only pipeline stage timing.
+ *
+ * The block-memo render path runs four distinct stages per content change
+ * (parse → transform → build → render). Which one dominates depends on the
+ * workload — plugin mix, document length, math density — and every
+ * optimization decision should start from that split, not from a guess.
+ * {@link measureStage} emits one `performance.measure` entry per stage
+ * execution, named `ai-markdown:stage:<stage>`, so any live
+ * PerformanceObserver (the DevTools Performance panel's tracing, the
+ * BlockMemoCompare story's profiler) can aggregate them without the
+ * library depending on the observer.
+ *
+ * Delivery contract: entries are cleared from the global User Timing
+ * buffer immediately after emission — already-registered observers still
+ * receive them (delivery is queued at creation), but buffer readers
+ * (`performance.getEntriesByType('measure')` in the console, late
+ * `buffered: true` observers) see nothing. That is the price of never
+ * growing the page-global buffer from a render hot path (~4 entries per
+ * streamed token, observer or not). The DevTools Performance panel is
+ * unaffected — it captures measures from the trace, not the buffer.
+ *
+ * Production builds fold {@link ENABLED} to `false` (bundler substitution
+ * via the shared `DEV` gate) and the whole thing costs one boolean check
+ * per stage; unbundled Node SSR pays the same boolean, evaluated from an
+ * env read done once at import.
+ *
+ * @module components/devStageTimings
+ */
+
+import { DEV } from '../devEnv';
+
+/** The stages of the block-memo render pipeline, in execution order.
+ *  Single source of truth: the union type, the emitted measure names, and
+ *  any display ordering (ProfilerPanel) all derive from this tuple. */
+export const PIPELINE_STAGES = ['parse', 'transform', 'build', 'render'] as const;
+export type PipelineStage = (typeof PIPELINE_STAGES)[number];
+
+/** Prefix for the emitted `performance.measure` entry names. */
+export const STAGE_MEASURE_PREFIX = 'ai-markdown:stage:';
+
+/** Hoisted name table — measure names are shared constants, not a fresh
+ *  template-literal allocation per call. */
+const STAGE_NAMES = Object.fromEntries(
+  PIPELINE_STAGES.map((stage) => [stage, `${STAGE_MEASURE_PREFIX}${stage}`])
+) as Record<PipelineStage, string>;
+
+/**
+ * One-time capability gate. Beyond the DEV check, probes the exact calls
+ * {@link measureStage} makes — the options-object `measure` overload AND
+ * `clearMeasures` — by performing them once. Environments that expose
+ * `performance.measure` but only support the legacy mark-name overloads
+ * (older jsdom, partial polyfills) fail the probe and are gated off
+ * permanently, instead of paying a thrown-and-swallowed exception per
+ * stage per token for the whole session.
+ */
+const ENABLED: boolean =
+  DEV &&
+  (() => {
+    if (
+      typeof performance === 'undefined' ||
+      typeof performance.measure !== 'function' ||
+      typeof performance.clearMeasures !== 'function'
+    ) {
+      return false;
+    }
+    try {
+      const probe = `${STAGE_MEASURE_PREFIX}probe`;
+      performance.measure(probe, { start: 0, end: 0 });
+      performance.clearMeasures(probe);
+      return true;
+    } catch {
+      return false;
+    }
+  })();
+
+/**
+ * Run `fn` as the named pipeline stage, emitting its `performance.measure`
+ * in dev. The single-callable shape (instead of a start/end pair) makes
+ * the stage name a typed argument and the pairing unforgettable: a call
+ * site cannot mismatch or drop an end call. If `fn` throws, no measure is
+ * emitted for the aborted stage.
+ */
+export function measureStage<T>(stage: PipelineStage, fn: () => T): T {
+  if (!ENABLED) return fn();
+  const start = performance.now();
+  const result = fn();
+  const name = STAGE_NAMES[stage];
+  // Probe-verified calls — no per-call try/catch needed. See the module
+  // docs for why the entry is cleared immediately after emission.
+  performance.measure(name, { start, end: performance.now() });
+  performance.clearMeasures(name);
+  return result;
+}

packages/core/stories/streaming/BlockMemoComparison.tsx

@@ -114,7 +114,10 @@ export const BlockMemoComparison = ({
   const payloadBlocks = useMemo(() => countBlocks(effectivePayload), [effectivePayload]);
   const scenarios = useMemo(() => buildScenarios(effectivePayload), [effectivePayload]);
 
-  const enabledProfiler = useRenderProfiler<HTMLDivElement>({ running });
+  // observeStages on the ENABLED side only: the stage measures are
+  // page-wide and only the block-memo path emits them — observing on both
+  // would print the same union under the legacy panel.
+  const enabledProfiler = useRenderProfiler<HTMLDivElement>({ running, observeStages: true });
   const disabledProfiler = useRenderProfiler<HTMLDivElement>({ running });
   const theme = getStreamingTheme(colorScheme);
 

packages/core/stories/streaming/IsolatedSide.tsx

@@ -46,7 +46,7 @@ export const IsolatedSide = () => {
   // property chains on a hook result that contains refs as ref accesses
   // during render; plain bindings keep the analyzer satisfied.
   const { snapshot, onRender, targetRef, recordChunk, recordElementRender, reset } =
-    useRenderProfiler<HTMLDivElement>({ running });
+    useRenderProfiler<HTMLDivElement>({ running, observeStages: mode === 'memo' });
   const theme = getStreamingTheme(scheme);
 
   // Slim the iframe's own viewport scrollbar too (the side page can be

packages/core/stories/streaming/ProfilerPanel.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import type { CSSProperties, ReactNode } from 'react';
+import { PIPELINE_STAGES } from '../../src/components/devStageTimings';
 import type { RenderProfilerSnapshot } from './useRenderProfiler';
 import { getStreamingTheme, type ColorScheme } from './theme';
 
@@ -13,6 +14,16 @@ function topTags(byTag: Record<string, number>, limit: number): Array<[string, n
     .slice(0, limit);
 }
 
+/** Panel fields for the observed pipeline stages, in pipeline order. Empty
+ *  when this profiler doesn't observe stage measures (legacy side). */
+function stageFields(snapshot: RenderProfilerSnapshot): Field[] {
+  return PIPELINE_STAGES.filter((k) => snapshot.stages[k]).map((k) => ({
+    label: `${k} avg (ms)`,
+    value: fmt(snapshot.stages[k].total / snapshot.stages[k].count),
+    sub: `Σ ${fmt(snapshot.stages[k].total, 0)} ms · ×${snapshot.stages[k].count} · max ${fmt(snapshot.stages[k].max, 1)}`,
+  }));
+}
+
 type Tone = 'good' | 'warn' | 'bad';
 
 interface Field {
@@ -40,6 +51,7 @@ export const ProfilerPanel = ({
   compact?: boolean;
 }) => {
   const theme = getStreamingTheme(colorScheme);
+  const stages = stageFields(snapshot);
 
   const sectionStyle: CSSProperties = {
     background: theme.panelBg,
@@ -127,6 +139,20 @@ export const ProfilerPanel = ({
         { label: 'max base (ms)', value: fmt(snapshot.base.max) },
       ],
     },
+    // Pipeline stage timings — present only when this profiler observes the
+    // dev-only `ai-markdown:stage:*` measures (block-memo side). Ordered by
+    // the shared PIPELINE_STAGES tuple so a stage added to the pipeline
+    // cannot be silently omitted from the panel.
+    ...(stages.length === 0
+      ? []
+      : [
+          {
+            title: 'Pipeline stages (dev-only)',
+            hint:
+              'per-execution timings from ai-markdown:stage:* performance measures, emitted by the block-memo path only. parse + transform run on every content change regardless of caching — they are the incremental-parse opportunity; render is where block-memo saves. render also fires on cache-hit-only re-renders, so its avg skews low by design.',
+            fields: stages,
+          },
+        ]),
     {
       title: 'Component renders',
       hint: 'spy customComponents count function-body invocations per tag (react-scan-style). Block-memo skips re-invoking components inside cached subtrees → totals diverge cleanly between paths.',

packages/core/stories/streaming/useRenderProfiler.ts

@@ -35,6 +35,7 @@
 
 import { useCallback, useEffect, useRef, useState } from 'react';
 import type { ProfilerOnRenderCallback, RefObject } from 'react';
+import { STAGE_MEASURE_PREFIX } from '../../src/components/devStageTimings';
 
 export interface ChunkSample {
   index: number;
@@ -86,6 +87,13 @@ export interface ElementRenderStats {
   byTag: Record<string, number>;
 }
 
+/** Aggregate of one pipeline stage's `performance.measure` entries. */
+export interface StageStats {
+  count: number;
+  total: number;
+  max: number;
+}
+
 export interface RenderProfilerSnapshot {
   /** Commits intentionally excluded from stats during JIT warm-up. */
   warmUpCommits: number;
@@ -117,6 +125,14 @@ export interface RenderProfilerSnapshot {
    * component level" — react-scan-style without DevTools hook hackery.
    */
   elementRenders: ElementRenderStats;
+  /**
+   * Dev-only pipeline stage timings (`ai-markdown:stage:*` performance
+   * measures emitted by the block-memo render path). Empty unless the hook
+   * was created with `observeStages: true` AND an instrumented (dev-build,
+   * block-memo) renderer is measuring on this page. Keyed by stage name
+   * (parse / transform / build / render).
+   */
+  stages: Record<string, StageStats>;
   chunks: ChunkSample[];
   totalChars: number;
   lastResetAt: number;
@@ -142,6 +158,13 @@ export interface RenderProfilerOptions {
    * task after the stream ends is still captured.
    */
   running?: boolean;
+  /**
+   * Aggregate `ai-markdown:stage:*` performance measures into
+   * `snapshot.stages`. Measures are PAGE-WIDE — in a same-page comparison
+   * only ONE profiler (the block-memo side's) should observe them, or both
+   * panels would display the same union. Default `false`.
+   */
+  observeStages?: boolean;
 }
 
 export interface RenderProfilerHandle<T extends HTMLElement = HTMLElement> {
@@ -203,6 +226,7 @@ export const emptySnapshot = (): RenderProfilerSnapshot => ({
   rafCount: 0,
   longTasks: emptyLongTasks(),
   elementRenders: emptyElementRenders(),
+  stages: {},
   chunks: [],
   totalChars: 0,
   lastResetAt: 0,
@@ -244,6 +268,8 @@ interface Accum {
   // Element render counter (driven by spy customComponents)
   elementRenderTotal: number;
   elementRenderByTag: Record<string, number>;
+  // Pipeline stage measures (observeStages only)
+  stages: Record<string, StageStats>;
   // Stream chunks
   chunks: ChunkSample[];
   totalChars: number;
@@ -279,6 +305,7 @@ const emptyAccum = (now: number): Accum => ({
   longTaskMax: 0,
   elementRenderTotal: 0,
   elementRenderByTag: {},
+  stages: {},
   chunks: [],
   totalChars: 0,
   lastResetAt: now,
@@ -329,6 +356,7 @@ export function useRenderProfiler<T extends HTMLElement = HTMLElement>(
   const maxSamples = opts?.maxSamples ?? 500;
   const snapshotMs = opts?.snapshotIntervalMs ?? 100;
   const running = opts?.running ?? true;
+  const observeStages = opts?.observeStages ?? false;
 
   // Lazy initialization to avoid calling `performance.now()` during render
   // (would trip React Compiler purity checks).
@@ -465,6 +493,7 @@ export function useRenderProfiler<T extends HTMLElement = HTMLElement>(
         total: acc.elementRenderTotal,
         byTag: { ...acc.elementRenderByTag },
       },
+      stages: Object.fromEntries(Object.entries(acc.stages).map(([k, v]) => [k, { ...v }])),
       chunks: acc.chunks.slice(),
       totalChars: acc.totalChars,
       lastResetAt: acc.lastResetAt,
@@ -549,6 +578,33 @@ export function useRenderProfiler<T extends HTMLElement = HTMLElement>(
     return () => obs.disconnect();
   }, []);
 
+  // PerformanceObserver measure — aggregates the dev-only pipeline stage
+  // timings the block-memo renderer emits (see src devStageTimings).
+  // Page-wide by nature; only enable on ONE profiler per page (the
+  // block-memo side), otherwise both panels show the same union.
+  useEffect(() => {
+    if (!observeStages || typeof PerformanceObserver === 'undefined') return;
+    let observer: PerformanceObserver | undefined;
+    try {
+      observer = new PerformanceObserver((list) => {
+        const acc = accumRef.current;
+        if (!acc) return;
+        for (const entry of list.getEntries()) {
+          if (!entry.name.startsWith(STAGE_MEASURE_PREFIX)) continue;
+          const stage = entry.name.slice(STAGE_MEASURE_PREFIX.length);
+          const s = (acc.stages[stage] ??= { count: 0, total: 0, max: 0 });
+          s.count += 1;
+          s.total += entry.duration;
+          if (entry.duration > s.max) s.max = entry.duration;
+        }
+      });
+      observer.observe({ entryTypes: ['measure'] });
+    } catch {
+      // measure observation unsupported — stage panel simply stays empty.
+    }
+    return () => observer?.disconnect();
+  }, [observeStages]);
+
   // PerformanceObserver longtask — main-thread blocks ≥ 50 ms, the kind
   // that produce visible jank. Page-wide (not per-side), so when two
   // profilers run in the same tab they will report identical numbers. Use