@ai-react-markdown/engine 2.9.1 → 2.10.0

package/dist/index.d.cts

@@ -1498,22 +1498,29 @@ declare const sanitizeSchema: Schema;
  * exactly the incremental-parse engine's fast path — the controller sits
  * upstream of the renderer and never touches the parse pipeline.
  *
- * Pacing model — an adaptive jitter buffer (audio-playout style):
- * - The controller estimates the source's arrival rate and burst interval
- *   with irregular-sampling EMAs (recorded on every append), and derives a
- *   target buffer B* ≈ bufferFactor × one burst's worth of text — the
- *   causality floor for smoothing bursts of that period.
- * - Streaming: rate = max(floor, rateEma + (backlog − B*) / correctionTau).
- *   Feedforward tracks the source speed (bounded lag at any model speed);
- *   the feedback term pins the backlog near B*, dipping BELOW the source
- *   rate on purpose when the buffer runs low so it can refill instead of
- *   running dry between bursts. The floor is a tiny anti-freeze trickle,
- *   deliberately smaller than any realistic arrival rate.
- * - Pre-stats (first burst after construction/snap): no estimate exists
- *   yet, so the backlog reveals over roughly one correction window.
+ * Pacing model — a completion-deadline law over a gap-quantile estimator
+ * (v2.10 redesign; the prior water-level jitter buffer's rationale and the
+ * falsified alternatives live in the archived design plan):
+ * - Every inter-arrival gap enters a small sliding window — there is NO
+ *   pause classifier. The target interval Î is a high quantile of that
+ *   window: two slow-gap confirmations flip the controller into a slower
+ *   mode, while leaving it takes the window turning over ("cautious
+ *   fast, aggressive slow").
+ * - Streaming: everything on hand should be on screen by the time the
+ *   next lump is expected. The horizon H = clamp(bufferFactor × Î + pad,
+ *   16, maxLagMs) stamps a deadline at the last arrival + H, and
+ *   rate = backlog / time-to-deadline — constant within a period, so a
+ *   coarse feed reads as an even typewriter, not pour-then-crawl. The
+ *   floor is a tiny anti-freeze trickle. `maxLagMs` is the preset's
+ *   max-lag promise AND the pause handler: a gap beyond it saturates H
+ *   and cannot change any further decision.
+ * - Pre-stats (first lump after construction/snap — no gap sample yet):
+ *   the backlog reveals over roughly one correction window.
  * - Finished: rate = backlog / time-to-deadline, deadline stamped at
- *   `finish() + drainMs` — the backlog empties BY the deadline instead of
- *   decaying toward it forever.
+ *   `finish()` + a rate-continuity window — the tail reveals at most
+ *   ~2× the stream's measured throughput, clamped to [drainMs, 3×drainMs]
+ *   — so the backlog empties BY the deadline without an end-of-message
+ *   pour.
  * - A deadline credit accumulator converts elapsed time (injectable
  *   `now()`) into whole-grapheme reveals per scheduled frame — timers
  *   carry no state between frames, so throttled/paused schedulers
@@ -1538,39 +1545,63 @@ declare const sanitizeSchema: Schema;
  * latency-vs-smoothness axis (the audio-plugin buffer-preset convention —
  * perceptual parameters resist meaningful numeric tuning).
  *
- * - `'smooth'` — target ~1.7 bursts of buffer: almost never runs dry
- *   between server flushes, at the cost of a little extra lag.
- * - `'balanced'` (default) — ~1 burst of buffer, the causality floor for
- *   smoothing: minimal lag that can still bridge a typical gap.
- * - `'responsive'` — sub-burst buffer: lowest lag, accepts an occasional
- *   visible pause between bursts.
+ * - `'smooth'` — ~1.7 delivery intervals of runway (max lag 3.5s): extra
+ *   slack between server flushes, the most delivery coarseness absorbed.
+ * - `'balanced'` (default) — ~1 interval of runway (max lag 2.5s): even
+ *   pacing for delivery intervals up to ~2.5s at minimal lag.
+ * - `'responsive'` — ~0.45 of an interval (max lag 0.8s): lowest lag,
+ *   accepts visible pauses on coarse or bursty delivery.
  */
 type SmoothStreamPacing = 'smooth' | 'balanced' | 'responsive';
 /** The numeric parameter bundle a {@link SmoothStreamPacing} preset names. */
 interface SmoothStreamPacingParams {
-    /** Target buffer as a multiple of one estimated burst's worth of text. */
+    /**
+     * Horizon multiple — "periods of runway": the reveal deadline sits this
+     * many expected delivery intervals after the last arrival. 1.0 means
+     * everything on hand is on screen just as the next chunk is expected.
+     */
     bufferFactor: number;
     /**
-     * Feedback time constant (ms): how fast the backlog is steered toward
-     * the target buffer. Also the pre-stats reveal window for the first
-     * burst, before any arrival estimate exists.
+     * Pre-stats reveal window (ms) for the FIRST lump of a stream, before
+     * any inter-arrival sample exists. The streaming path no longer reads
+     * it — the v2.10 deadline law replaced the old feedback term it used to
+     * time-constant.
      */
     correctionTauMs: number;
-    /** Smoothing horizon (ms) for the arrival-rate / burst-interval EMAs. */
+    /**
+     * @deprecated Read by nothing since the v2.10 deadline-law redesign (it
+     * used to be the EMA horizon AND, harmfully, the pause-classifier
+     * threshold — the "1.8s cliff"). Kept in the preset objects so their
+     * exported shape is unchanged; setting it has no effect.
+     */
     emaTauMs: number;
+    /**
+     * The preset's max-lag promise (ms): the reveal DEADLINE never targets
+     * more than this far behind the live source (a throttled scheduler can
+     * transiently exceed it; the next tick self-corrects). It is also the
+     * whole pause story —
+     * a gap longer than `maxLagMs / bufferFactor` saturates the horizon and
+     * cannot change any further decision. Pay-per-use: a fine-grained
+     * stream's horizon tracks its own (small) cadence and never approaches
+     * this cap. Full smoothing of a coarse feed requires
+     * delivery-interval ≤ maxLagMs (bufferFactor ≥ 1 presets); steady mean
+     * lag there is about half the delivery period.
+     */
+    maxLagMs?: number;
     /**
      * Anti-freeze floor (grapheme clusters/s). Deliberately tiny — smaller
-     * than any realistic arrival rate — so the feedback term can slow the
-     * reveal below the source rate to refill the buffer, without ever
-     * freezing visible progress entirely.
+     * than any realistic arrival rate — a last-resort trickle so visible
+     * progress never freezes entirely while anything is pending.
      */
     minCharsPerSecond: number;
     /**
-     * Hard drain budget after {@link SmoothStreamController.finish}: a
-     * deadline is stamped at `finish() + drainMs` and the rate scales with
-     * remaining-backlog / remaining-time, so the backlog empties BY the
-     * deadline (not asymptotically). Consumed when the deadline is stamped —
-     * changing it affects the next drain, not one in progress.
+     * Drain-budget FLOOR after {@link SmoothStreamController.finish}: the
+     * drain deadline is stamped at `finish()` plus a rate-continuity window
+     * — enough time that the tail reveals at ~2× the stream's measured
+     * throughput — clamped to `[drainMs, 3 × drainMs]`. Short backlogs
+     * behave exactly as the pre-v2.10 fixed window did. Consumed when the
+     * deadline is stamped — changing it affects the next drain, not one in
+     * progress.
      */
     drainMs: number;
 }
@@ -1609,8 +1640,9 @@ interface SmoothStreamController {
     update(source: string): void;
     /**
      * Signals end of stream: confirms the held-back trailing grapheme and
-     * switches the control law to the `drainMs` window. Not terminal —
-     * a later {@link update} resumes animation.
+     * switches the control law to the rate-continuity drain window (floored
+     * at `drainMs`). Not terminal — a later {@link update} resumes
+     * animation.
      */
     finish(): void;
     /** Jumps to `source` instantly, no animation, and clears any backlog.

package/dist/index.d.ts

@@ -1498,22 +1498,29 @@ declare const sanitizeSchema: Schema;
  * exactly the incremental-parse engine's fast path — the controller sits
  * upstream of the renderer and never touches the parse pipeline.
  *
- * Pacing model — an adaptive jitter buffer (audio-playout style):
- * - The controller estimates the source's arrival rate and burst interval
- *   with irregular-sampling EMAs (recorded on every append), and derives a
- *   target buffer B* ≈ bufferFactor × one burst's worth of text — the
- *   causality floor for smoothing bursts of that period.
- * - Streaming: rate = max(floor, rateEma + (backlog − B*) / correctionTau).
- *   Feedforward tracks the source speed (bounded lag at any model speed);
- *   the feedback term pins the backlog near B*, dipping BELOW the source
- *   rate on purpose when the buffer runs low so it can refill instead of
- *   running dry between bursts. The floor is a tiny anti-freeze trickle,
- *   deliberately smaller than any realistic arrival rate.
- * - Pre-stats (first burst after construction/snap): no estimate exists
- *   yet, so the backlog reveals over roughly one correction window.
+ * Pacing model — a completion-deadline law over a gap-quantile estimator
+ * (v2.10 redesign; the prior water-level jitter buffer's rationale and the
+ * falsified alternatives live in the archived design plan):
+ * - Every inter-arrival gap enters a small sliding window — there is NO
+ *   pause classifier. The target interval Î is a high quantile of that
+ *   window: two slow-gap confirmations flip the controller into a slower
+ *   mode, while leaving it takes the window turning over ("cautious
+ *   fast, aggressive slow").
+ * - Streaming: everything on hand should be on screen by the time the
+ *   next lump is expected. The horizon H = clamp(bufferFactor × Î + pad,
+ *   16, maxLagMs) stamps a deadline at the last arrival + H, and
+ *   rate = backlog / time-to-deadline — constant within a period, so a
+ *   coarse feed reads as an even typewriter, not pour-then-crawl. The
+ *   floor is a tiny anti-freeze trickle. `maxLagMs` is the preset's
+ *   max-lag promise AND the pause handler: a gap beyond it saturates H
+ *   and cannot change any further decision.
+ * - Pre-stats (first lump after construction/snap — no gap sample yet):
+ *   the backlog reveals over roughly one correction window.
  * - Finished: rate = backlog / time-to-deadline, deadline stamped at
- *   `finish() + drainMs` — the backlog empties BY the deadline instead of
- *   decaying toward it forever.
+ *   `finish()` + a rate-continuity window — the tail reveals at most
+ *   ~2× the stream's measured throughput, clamped to [drainMs, 3×drainMs]
+ *   — so the backlog empties BY the deadline without an end-of-message
+ *   pour.
  * - A deadline credit accumulator converts elapsed time (injectable
  *   `now()`) into whole-grapheme reveals per scheduled frame — timers
  *   carry no state between frames, so throttled/paused schedulers
@@ -1538,39 +1545,63 @@ declare const sanitizeSchema: Schema;
  * latency-vs-smoothness axis (the audio-plugin buffer-preset convention —
  * perceptual parameters resist meaningful numeric tuning).
  *
- * - `'smooth'` — target ~1.7 bursts of buffer: almost never runs dry
- *   between server flushes, at the cost of a little extra lag.
- * - `'balanced'` (default) — ~1 burst of buffer, the causality floor for
- *   smoothing: minimal lag that can still bridge a typical gap.
- * - `'responsive'` — sub-burst buffer: lowest lag, accepts an occasional
- *   visible pause between bursts.
+ * - `'smooth'` — ~1.7 delivery intervals of runway (max lag 3.5s): extra
+ *   slack between server flushes, the most delivery coarseness absorbed.
+ * - `'balanced'` (default) — ~1 interval of runway (max lag 2.5s): even
+ *   pacing for delivery intervals up to ~2.5s at minimal lag.
+ * - `'responsive'` — ~0.45 of an interval (max lag 0.8s): lowest lag,
+ *   accepts visible pauses on coarse or bursty delivery.
  */
 type SmoothStreamPacing = 'smooth' | 'balanced' | 'responsive';
 /** The numeric parameter bundle a {@link SmoothStreamPacing} preset names. */
 interface SmoothStreamPacingParams {
-    /** Target buffer as a multiple of one estimated burst's worth of text. */
+    /**
+     * Horizon multiple — "periods of runway": the reveal deadline sits this
+     * many expected delivery intervals after the last arrival. 1.0 means
+     * everything on hand is on screen just as the next chunk is expected.
+     */
     bufferFactor: number;
     /**
-     * Feedback time constant (ms): how fast the backlog is steered toward
-     * the target buffer. Also the pre-stats reveal window for the first
-     * burst, before any arrival estimate exists.
+     * Pre-stats reveal window (ms) for the FIRST lump of a stream, before
+     * any inter-arrival sample exists. The streaming path no longer reads
+     * it — the v2.10 deadline law replaced the old feedback term it used to
+     * time-constant.
      */
     correctionTauMs: number;
-    /** Smoothing horizon (ms) for the arrival-rate / burst-interval EMAs. */
+    /**
+     * @deprecated Read by nothing since the v2.10 deadline-law redesign (it
+     * used to be the EMA horizon AND, harmfully, the pause-classifier
+     * threshold — the "1.8s cliff"). Kept in the preset objects so their
+     * exported shape is unchanged; setting it has no effect.
+     */
     emaTauMs: number;
+    /**
+     * The preset's max-lag promise (ms): the reveal DEADLINE never targets
+     * more than this far behind the live source (a throttled scheduler can
+     * transiently exceed it; the next tick self-corrects). It is also the
+     * whole pause story —
+     * a gap longer than `maxLagMs / bufferFactor` saturates the horizon and
+     * cannot change any further decision. Pay-per-use: a fine-grained
+     * stream's horizon tracks its own (small) cadence and never approaches
+     * this cap. Full smoothing of a coarse feed requires
+     * delivery-interval ≤ maxLagMs (bufferFactor ≥ 1 presets); steady mean
+     * lag there is about half the delivery period.
+     */
+    maxLagMs?: number;
     /**
      * Anti-freeze floor (grapheme clusters/s). Deliberately tiny — smaller
-     * than any realistic arrival rate — so the feedback term can slow the
-     * reveal below the source rate to refill the buffer, without ever
-     * freezing visible progress entirely.
+     * than any realistic arrival rate — a last-resort trickle so visible
+     * progress never freezes entirely while anything is pending.
      */
     minCharsPerSecond: number;
     /**
-     * Hard drain budget after {@link SmoothStreamController.finish}: a
-     * deadline is stamped at `finish() + drainMs` and the rate scales with
-     * remaining-backlog / remaining-time, so the backlog empties BY the
-     * deadline (not asymptotically). Consumed when the deadline is stamped —
-     * changing it affects the next drain, not one in progress.
+     * Drain-budget FLOOR after {@link SmoothStreamController.finish}: the
+     * drain deadline is stamped at `finish()` plus a rate-continuity window
+     * — enough time that the tail reveals at ~2× the stream's measured
+     * throughput — clamped to `[drainMs, 3 × drainMs]`. Short backlogs
+     * behave exactly as the pre-v2.10 fixed window did. Consumed when the
+     * deadline is stamped — changing it affects the next drain, not one in
+     * progress.
      */
     drainMs: number;
 }
@@ -1609,8 +1640,9 @@ interface SmoothStreamController {
     update(source: string): void;
     /**
      * Signals end of stream: confirms the held-back trailing grapheme and
-     * switches the control law to the `drainMs` window. Not terminal —
-     * a later {@link update} resumes animation.
+     * switches the control law to the rate-continuity drain window (floored
+     * at `drainMs`). Not terminal — a later {@link update} resumes
+     * animation.
      */
     finish(): void;
     /** Jumps to `source` instantly, no animation, and clears any backlog.

package/dist/index.dev.cjs

@@ -4443,24 +4443,32 @@ var SMOOTH_STREAM_PACING_PRESETS = Object.freeze({
     correctionTauMs: 280,
     emaTauMs: 2600,
     minCharsPerSecond: 4,
-    drainMs: 320
+    drainMs: 320,
+    maxLagMs: 3500
   }),
   balanced: Object.freeze({
     bufferFactor: 1,
     correctionTauMs: 180,
     emaTauMs: 1800,
     minCharsPerSecond: 6,
-    drainMs: 240
+    drainMs: 240,
+    maxLagMs: 2500
   }),
   responsive: Object.freeze({
     bufferFactor: 0.45,
     correctionTauMs: 110,
     emaTauMs: 1100,
     minCharsPerSecond: 10,
-    drainMs: 150
+    drainMs: 150,
+    maxLagMs: 800
   })
 });
-var MAX_TARGET_BUFFER_MS = 1200;
+var GAP_WINDOW = 16;
+var INTERVAL_QUANTILE = 0.9;
+var HORIZON_PAD_MS = 50;
+var DEADLINE_FLOOR_MS = 33;
+var DRAIN_CATCHUP_FACTOR = 2;
+var DRAIN_MAX_FACTOR = 3;
 var defaultNow = typeof performance !== "undefined" && typeof performance.now === "function" ? () => performance.now() : () => Date.now();
 var defaultSchedule = (cb) => {
   if (typeof requestAnimationFrame === "function") {
@@ -4511,18 +4519,18 @@ var createSmoothStreamController = (options = {}) => {
   let lastTickAt = 0;
   let cancelFrame;
   let disposed = false;
-  let rateEma;
-  let intervalEma;
+  let gapWindow = [];
   let lastArrivalAt;
   const listeners = /* @__PURE__ */ new Set();
   const resolveParams = () => {
-    const preset = SMOOTH_STREAM_PACING_PRESETS[options.pacing] ?? SMOOTH_STREAM_PACING_PRESETS.balanced;
+    const preset = Object.hasOwn(SMOOTH_STREAM_PACING_PRESETS, options.pacing) ? SMOOTH_STREAM_PACING_PRESETS[options.pacing] : SMOOTH_STREAM_PACING_PRESETS.balanced;
     return {
       bufferFactor: finiteOr(options.bufferFactor, preset.bufferFactor),
       correctionTauMs: finiteOr(options.correctionTauMs, preset.correctionTauMs),
       emaTauMs: finiteOr(options.emaTauMs, preset.emaTauMs),
       minCharsPerSecond: finiteOr(options.minCharsPerSecond, preset.minCharsPerSecond),
-      drainMs: finiteOr(options.drainMs, preset.drainMs)
+      drainMs: finiteOr(options.drainMs, preset.drainMs),
+      maxLagMs: finiteOr(options.maxLagMs, preset.maxLagMs ?? 2500)
     };
   };
   const recordArrival = (t, added) => {
@@ -4533,12 +4541,8 @@ var createSmoothStreamController = (options = {}) => {
     }
     const gap = Math.max(1, t - lastArrivalAt);
     lastArrivalAt = t;
-    const tau = Math.max(1, resolveParams().emaTauMs);
-    if (gap > tau) return;
-    const alpha = 1 - Math.exp(-gap / tau);
-    const instantRate = added * 1e3 / gap;
-    rateEma = (rateEma ?? 0) + alpha * (instantRate - (rateEma ?? 0));
-    intervalEma = (intervalEma ?? 0) + alpha * (gap - (intervalEma ?? 0));
+    gapWindow.push({ gap, added });
+    if (gapWindow.length > GAP_WINDOW) gapWindow.shift();
   };
   const notify = () => {
     visibleCache = source.slice(0, visibleEnd);
@@ -4564,15 +4568,12 @@ var createSmoothStreamController = (options = {}) => {
     let rate;
     if (finished && drainDeadlineAt !== void 0) {
       rate = Math.max(params.minCharsPerSecond, pending.length * 1e3 / Math.max(1, drainDeadlineAt - t));
-    } else if (rateEma !== void 0 && intervalEma !== void 0) {
-      const targetBuffer = Math.max(
-        1,
-        Math.min(params.bufferFactor * rateEma * (intervalEma / 1e3), rateEma * MAX_TARGET_BUFFER_MS / 1e3)
-      );
-      rate = Math.max(
-        params.minCharsPerSecond,
-        rateEma + (pending.length - targetBuffer) * 1e3 / Math.max(1, params.correctionTauMs)
-      );
+    } else if (gapWindow.length > 0 && lastArrivalAt !== void 0) {
+      const gaps = gapWindow.map((s) => s.gap).sort((a, b) => a - b);
+      const intervalQ = gaps[Math.min(gaps.length - 1, Math.floor(gaps.length * INTERVAL_QUANTILE))];
+      const horizon = Math.max(16, Math.min(params.bufferFactor * intervalQ + HORIZON_PAD_MS, params.maxLagMs));
+      const deadline = Math.max(lastArrivalAt + horizon, t + DEADLINE_FLOOR_MS);
+      rate = Math.max(params.minCharsPerSecond, pending.length * 1e3 / Math.max(1, deadline - t));
     } else {
       rate = Math.max(params.minCharsPerSecond, pending.length * 1e3 / Math.max(1, params.correctionTauMs));
     }
@@ -4618,8 +4619,7 @@ var createSmoothStreamController = (options = {}) => {
     initialized = true;
     finished = false;
     drainDeadlineAt = void 0;
-    rateEma = void 0;
-    intervalEma = void 0;
+    gapWindow = [];
     lastArrivalAt = void 0;
     source = next;
     visibleEnd = next.length;
@@ -4656,10 +4656,26 @@ var createSmoothStreamController = (options = {}) => {
       if (finished) return;
       finished = true;
       lastArrivalAt = void 0;
-      drainDeadlineAt = now() + resolveParams().drainMs;
       if (tentativeEnd > (pending.length > 0 ? pending[pending.length - 1] : visibleEnd)) {
         pending.push(tentativeEnd);
       }
+      const params = resolveParams();
+      let drainWin = params.drainMs;
+      let chars = 0;
+      let ms = 0;
+      for (let i = 0; i < gapWindow.length - 1; i += 1) {
+        chars += gapWindow[i].added;
+        ms += gapWindow[i].gap;
+      }
+      const backlog = source.length - visibleEnd;
+      if (chars > 0 && ms > 0 && backlog > 0) {
+        const throughput = chars * 1e3 / ms;
+        drainWin = Math.min(
+          Math.max(backlog * 1e3 / (DRAIN_CATCHUP_FACTOR * throughput), params.drainMs),
+          DRAIN_MAX_FACTOR * params.drainMs
+        );
+      }
+      drainDeadlineAt = now() + drainWin;
       seam = source.length;
       ensureScheduled();
     },