@simon_he/vue-tui 0.0.6 → 0.0.8

package/dist/index.d.ts

@@ -1,99 +1,11 @@
+import { AnsiColorName, BufferSnapshot, Cell, Style, TERMINAL_RENDER_PLANES, Terminal, TerminalCommitEvent, TerminalEventMap, TerminalRenderPlane, TerminalRenderPlanes, TerminalResizeEvent, TerminalScrollOperation, ThemeModeId } from "./types-ClIV2h1o.js";
+import { TuiMarkdownTheme, TuiMarkdownThemeOverrides } from "./theme-Bsm65g8k.js";
 import * as vue15 from "vue";
 import * as vue16 from "vue";
 import { App, Component as Component$1, ComputedRef, InjectionKey, Ref, VNode } from "vue";
 
-//#region src/core/render-plane.d.ts
-declare const TERMINAL_RENDER_PLANES: readonly ["default", "transcript", "chrome", "overlay"];
-type TerminalRenderPlane = (typeof TERMINAL_RENDER_PLANES)[number];
-type TerminalRenderPlanes = readonly TerminalRenderPlane[];
-
-//#endregion
-//#region src/core/types.d.ts
-type AnsiColorName = 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'white' | 'blackBright' | 'redBright' | 'greenBright' | 'yellowBright' | 'blueBright' | 'magentaBright' | 'cyanBright' | 'whiteBright';
-type Style = Readonly<{
-  fg?: AnsiColorName;
-  bg?: AnsiColorName;
-  bold?: boolean;
-  dim?: boolean;
-  italic?: boolean;
-  underline?: boolean;
-  inverse?: boolean;
-  /**
-   * Optional terminal hyperlink target (OSC 8).
-   * When set, renderers may emit a clickable hyperlink while keeping text width unchanged.
-   */
-  href?: string;
-}>;
-type Cell = Readonly<{
-  ch: string;
-  width: 1 | 2;
-  continuation?: true;
-  style: Style;
-}>;
-type BufferSnapshot = Readonly<{
-  cols: number;
-  rows: number;
-  lines: readonly string[];
-}>;
-type TerminalSize = Readonly<{
-  cols: number;
-  rows: number;
-}>;
-type TerminalScrollOperation = Readonly<{
-  startY: number;
-  endY: number;
-  delta: number;
-}>;
-type TerminalCommitEvent = Readonly<{
-  dirtyRows: readonly number[] | null;
-  planes: TerminalRenderPlanes | null;
-  sync?: boolean;
-  scrollOperations?: readonly TerminalScrollOperation[] | null;
-}>;
-type TerminalResizeEvent = Readonly<{
-  cols: number;
-  rows: number;
-}>;
-interface TerminalEventMap {
-  commit: TerminalCommitEvent;
-  resize: TerminalResizeEvent;
-}
-interface Terminal {
-  resize: (cols: number, rows: number) => void;
-  clear: (x?: number, y?: number, w?: number, h?: number) => void;
-  write: (text: string, opts?: {
-    x?: number;
-    y?: number;
-    style?: Style;
-  }) => void;
-  writeAnsi: (text: string, opts?: {
-    x?: number;
-    y?: number;
-  }) => void;
-  put: (x: number, y: number, ch: string, style?: Style) => void;
-  fill: (x: number, y: number, w: number, h: number, ch?: string, style?: Style) => void;
-  scroll: (lines: number) => void;
-  setCursor: (x: number, y: number, visible?: boolean) => void;
-  batch: <T>(fn: () => T) => T;
-  commit: (meta?: {
-    planes?: TerminalRenderPlanes | null;
-    sync?: boolean;
-  }) => readonly number[] | null;
-  on: <K extends keyof TerminalEventMap>(event: K, cb: (payload: TerminalEventMap[K]) => void) => () => void;
-  dispose: () => void;
-  size: () => TerminalSize;
-  snapshot: () => BufferSnapshot;
-  getCell: (x: number, y: number) => Cell;
-  getRow: (y: number) => readonly Cell[];
-  setScrollbackLimit: (limit: number) => void;
-  getScrollbackLines: (count?: number) => readonly string[];
-  /** Register fingerprint function for SoA pre-computation on the composite buffer. */
-  setFingerprintFn: (fn: (ch: string, style: Style) => number) => void;
-  /** Get pre-computed fingerprints for a composite buffer row (null if not enabled). */
-  getRowFingerprints: (y: number) => Uint32Array | null;
-} //#endregion
 //#region src/core/ansi/colors.d.ts
-type TerminalColorMode = 'ansi8' | 'ansi16' | 'ansi256' | 'truecolor';
+type TerminalColorMode = "ansi8" | "ansi16" | "ansi256" | "truecolor";
 type TerminalColorLevel = 8 | 16 | 256;
 type AnsiRgb = Readonly<{
   r: number;
@@ -103,9 +15,7 @@ type AnsiRgb = Readonly<{
 declare const SGR_RESET = "\u001B[0m";
 declare function truecolorFgOpen(rgb: AnsiRgb): string;
 declare function truecolorBgOpen(rgb: AnsiRgb): string;
-declare function rgbToAnsi256(rgb: AnsiRgb): number;
-
-//#endregion
+declare function rgbToAnsi256(rgb: AnsiRgb): number; //#endregion
 //#region src/ansi-styles.d.ts
 declare const ansiStyles: Readonly<{
   reset: Readonly<{
@@ -307,7 +217,7 @@ declare function ansiColors(level: 8 | 16 | 256): readonly Readonly<{
 }>[]; //#endregion
 //#region src/events/recording.d.ts
 type TerminalEventRecord = Readonly<{
-  type: 'keydown' | 'keyup';
+  type: "keydown" | "keyup";
   key: string;
   code?: string;
   ctrlKey?: boolean;
@@ -317,7 +227,7 @@ type TerminalEventRecord = Readonly<{
   repeat?: boolean;
   time?: number;
 }> | Readonly<{
-  type: 'pointerdown' | 'pointerup' | 'pointermove' | 'click' | 'dblclick' | 'contextmenu';
+  type: "pointerdown" | "pointerup" | "pointermove" | "click" | "dblclick" | "contextmenu";
   cellX: number;
   cellY: number;
   clientX?: number;
@@ -330,19 +240,20 @@ type TerminalEventRecord = Readonly<{
   metaKey?: boolean;
   time?: number;
 }> | Readonly<{
-  type: 'wheel';
+  type: "wheel";
   cellX: number;
   cellY: number;
   clientX?: number;
   clientY?: number;
   deltaY: number;
+  deltaMode?: number;
   ctrlKey?: boolean;
   shiftKey?: boolean;
   altKey?: boolean;
   metaKey?: boolean;
   time?: number;
 }> | Readonly<{
-  type: 'beforeinput' | 'input' | 'compositionstart' | 'compositionupdate' | 'compositionend' | 'paste';
+  type: "beforeinput" | "input" | "compositionstart" | "compositionupdate" | "compositionend" | "paste";
   data?: string;
   inputType?: string;
   isComposing?: boolean;
@@ -353,6 +264,7 @@ type TerminalEventRecord = Readonly<{
 //#endregion
 //#region src/cli/input.d.ts
 type Stdin = NodeJS.ReadStream;
+type KeyboardProtocol = "auto" | "kitty" | "xterm" | "off";
 type StdinDriver = Readonly<{
   dispose: () => void;
 }>;
@@ -360,7 +272,9 @@ declare function createStdinDriver(options: Readonly<{
   dispatch: (event: TerminalEventRecord) => boolean | void;
   stdin?: Stdin;
   stdout?: NodeJS.WriteStream;
+  env?: Readonly<Record<string, unknown>>;
   enableMouse?: boolean;
+  keyboardProtocol?: KeyboardProtocol;
   /**
    * Enable "any-motion" mouse tracking (xterm DECSET ?1003).
    * This is required for hover interactions in the CLI, but can increase event volume.
@@ -372,9 +286,9 @@ declare function createStdinDriver(options: Readonly<{
 
 //#endregion
 //#region src/cli/path-suggest-core.d.ts
-type PathPickMode = 'directory' | 'file' | 'any';
+type PathPickMode = "directory" | "file" | "any";
 type PathSuggestion = Readonly<{
-  kind: 'directory' | 'file';
+  kind: "directory" | "file";
   display: string;
   completion: string;
   absPath: string;
@@ -388,7 +302,7 @@ type SuggestPathsResult = Readonly<{
 
 //#endregion
 //#region src/cli/path-provider.d.ts
-type FsEntryKind = 'file' | 'directory' | 'other';
+type FsEntryKind = "file" | "directory" | "other";
 type FsDirEntry = Readonly<{
   name: string;
   kind: FsEntryKind;
@@ -407,7 +321,7 @@ type PathPickerProvider = Readonly<{
     max: number;
     showHidden?: boolean;
     maxDepth?: number;
-    gitignore?: 'blocking' | 'nonBlocking';
+    gitignore?: "blocking" | "nonBlocking";
   }>) => Promise<SuggestPathsResult>;
   resolvePath?: (workspaceAbs: string, input: string) => string | Promise<string>;
 }>;
@@ -423,7 +337,7 @@ declare function suggestPaths(options: Readonly<{
   showHidden?: boolean;
   listDir: (absDir: string) => Promise<FsDirEntry[]>;
   maxDepth?: number;
-  gitignore?: 'blocking' | 'nonBlocking';
+  gitignore?: "blocking" | "nonBlocking";
 }>): Promise<SuggestPathsResult>;
 declare function resolveUserPath(workspaceAbs: string, input: string): string;
 
@@ -455,6 +369,10 @@ declare function detectTerminalColorCapability(opts?: Readonly<{
   platform?: string;
 }>): TerminalColorCapability;
 
+//#endregion
+//#region src/core/ansi-palette.d.ts
+type ThemePalette = Partial<Record<AnsiColorName, string>>;
+
 //#endregion
 //#region src/core/ansi/sgr.d.ts
 interface AnsiSegment {
@@ -474,19 +392,132 @@ declare function createTerminal(opts: {
   rows: number;
 }): Terminal;
 
+//#endregion
+//#region src/renderer/capabilities.d.ts
+type RendererCapabilities = Readonly<{
+  syncFlush: boolean;
+  scrollOperations: boolean;
+  domRows: boolean;
+}>;
+type TerminalRendererLike = Readonly<{
+  capabilities: RendererCapabilities;
+  container?: HTMLElement;
+  debugStats?: unknown;
+}>;
+declare const DOM_RENDERER_CAPABILITIES: RendererCapabilities;
+declare const HEADLESS_RENDERER_CAPABILITIES: RendererCapabilities;
+
 //#endregion
 //#region src/renderer/dom/dom-renderer.d.ts
 type CellMetrics = Readonly<{
   cellWidth: number;
   cellHeight: number;
 }>;
+type DomRendererSyncFlushDecision = Readonly<{
+  performed: boolean;
+  deferredReason?: "budget";
+  rows: number;
+  planes: number;
+  cells: number;
+  maxRows: number;
+  maxCells: number;
+}>;
+type DomRendererSyncFlushStats = Readonly<{
+  requested: number;
+  performed: number;
+  deferred: number;
+  last: DomRendererSyncFlushDecision | null;
+}>;
+type DomRendererFlushSample = Readonly<{
+  mode: "sync" | "deferred";
+  startedAt: number;
+  durationMs: number;
+  planeRows: number;
+  planes: number;
+}>;
+type DomRendererFlushStats = Readonly<{
+  count: number;
+  last: DomRendererFlushSample | null;
+}>;
+type DomRendererRowRenderStats = Readonly<{
+  rows: number;
+  cacheHits: number;
+  rowKeyPrepassChecks: number;
+  rowKeyPrepassHits: number;
+  rowKeyPrepassMisses: number;
+  transparentBlankRows: number;
+  plainTextRows: number;
+  singleStyledRows: number;
+  segmentReuseRows: number;
+  fragmentRows: number;
+  spansCreated: number;
+  spansReused: number;
+  textNodeUpdates: number;
+  replaceChildren: number;
+}>;
+type DomRendererRowRenderDebugStats = Readonly<{
+  total: DomRendererRowRenderStats;
+  lastFlush: DomRendererRowRenderStats | null;
+}>;
+type DomRendererRowKeyPrepassMode = boolean | "auto";
+type DomRendererRowKeyPrepassDecision = "forced-enabled" | "forced-disabled" | "sampling" | "enabled" | "disabled";
+type DomRendererRowKeyPrepassDebugStats = Readonly<{
+  mode: DomRendererRowKeyPrepassMode;
+  decision: DomRendererRowKeyPrepassDecision;
+  sampleRows: number;
+  sampleHits: number;
+  sampleMisses: number;
+  sampleHitRatio: number | null;
+  lastSampleRows: number;
+  lastSampleHitRatio: number | null;
+}>;
+type DomRendererDebugStats = Readonly<{
+  syncFlush: DomRendererSyncFlushStats;
+  flush: DomRendererFlushStats;
+  rowRender: DomRendererRowRenderDebugStats;
+  rowKeyPrepass: DomRendererRowKeyPrepassDebugStats;
+}>;
 interface DomRenderer {
   readonly container: HTMLElement;
+  readonly capabilities: RendererCapabilities;
+  readonly debugStats: DomRendererDebugStats;
   readonly metrics: CellMetrics;
   dispose: () => void;
   refresh: () => void;
+  updateTheme: (next: Readonly<{
+    palette?: ThemePalette | null;
+  }>) => void;
+  setPlaneOffset: (plane: TerminalRenderPlane, offsetPx: number) => void;
+  setPlaneViewport: (plane: TerminalRenderPlane, viewport: Readonly<{
+    topPx: number;
+    heightPx: number;
+  }> | null) => void;
 }
-declare function createDomRenderer(terminal: Terminal, container: HTMLElement): DomRenderer;
+interface DomRendererOptions {
+  /**
+   * Maximum dirty row count allowed for same-call DOM flush when commit({ sync: true }).
+   * Larger updates are rAF-batched to avoid blocking the main thread.
+   */
+  syncFlushMaxRows?: number;
+  /**
+   * Maximum estimated cell work for sync DOM flush: dirtyRows * cols * activePlanes.
+   */
+  syncFlushCellBudget?: number;
+  /**
+   * Enables DOM line-node shifting for terminal scrollOperations.
+   */
+  enableScrollOperations?: boolean;
+  /** Optional ANSI-name palette exposed as DOM CSS variables. */
+  palette?: ThemePalette | null;
+  /**
+   * Controls a key-only early bailout before row segment allocation.
+   * The normal row cache remains enabled regardless of this option.
+   * Defaults to "auto": sample cached-row hit ratio and keep prepass enabled only
+   * when it pays for itself.
+   */
+  enableRowKeyPrepass?: DomRendererRowKeyPrepassMode;
+}
+declare function createDomRenderer(terminal: Terminal, container: HTMLElement, options?: DomRendererOptions): DomRenderer;
 
 //#endregion
 //#region src/events/manager/types.d.ts
@@ -496,7 +527,7 @@ type Rect = Readonly<{
   w: number;
   h: number;
 }>;
-type TerminalEventType = 'click' | 'dblclick' | 'contextmenu' | 'pointerdown' | 'pointerup' | 'pointermove' | 'pointerenter' | 'pointerleave' | 'wheel' | 'keydown' | 'keyup' | 'beforeinput' | 'input' | 'compositionstart' | 'compositionupdate' | 'compositionend' | 'paste' | 'focus' | 'blur';
+type TerminalEventType = "click" | "dblclick" | "contextmenu" | "pointerdown" | "pointerup" | "pointermove" | "pointerenter" | "pointerleave" | "wheel" | "keydown" | "keyup" | "beforeinput" | "input" | "compositionstart" | "compositionupdate" | "compositionend" | "paste" | "focus" | "blur";
 interface TerminalBaseEvent {
   type: TerminalEventType;
   target: TerminalNode | null;
@@ -523,6 +554,7 @@ type TerminalPointerEvent = TerminalBaseEvent & {
   altKey?: boolean;
   metaKey?: boolean;
   deltaY?: number;
+  deltaMode?: number;
 };
 type TerminalKeyboardEvent = TerminalBaseEvent & {
   key: string;
@@ -600,10 +632,10 @@ type TerminalDebugNode = Readonly<{
 //#endregion
 //#region src/events/manager/cli-event-manager.d.ts
 interface CliEventManager {
-  register: (node: Omit<TerminalNode, 'id'> & {
+  register: (node: Omit<TerminalNode, "id"> & {
     id?: string;
   }) => TerminalNode;
-  update: (id: string, next: Partial<Omit<TerminalNode, 'id'>>) => void;
+  update: (id: string, next: Partial<Omit<TerminalNode, "id">>) => void;
   unregister: (id: string) => void;
   setMetrics: (next: CellMetrics) => void;
   focus: (id: string | null) => void;
@@ -620,10 +652,10 @@ declare function createCliEventManager(options?: Readonly<{
 //#endregion
 //#region src/events/manager/event-manager.d.ts
 interface EventManager {
-  register: (node: Omit<TerminalNode, 'id'> & {
+  register: (node: Omit<TerminalNode, "id"> & {
     id?: string;
   }) => TerminalNode;
-  update: (id: string, next: Partial<Omit<TerminalNode, 'id'>>) => void;
+  update: (id: string, next: Partial<Omit<TerminalNode, "id">>) => void;
   unregister: (id: string) => void;
   setMetrics: (next: CellMetrics) => void;
   focus: (id: string | null) => void;
@@ -638,36 +670,6 @@ declare function createEventManager(container: HTMLElement, metrics: CellMetrics
   onFocusChange?: (prev: string | null, next: string | null) => void;
 }>): EventManager;
 
-//#endregion
-//#region src/observability/trace.d.ts
-type TraceRecord = Readonly<{
-  type: 'event';
-  at: number;
-  event: TerminalEventRecord;
-}> | Readonly<{
-  type: 'focus';
-  at: number;
-  prev: string | null;
-  next: string | null;
-}> | Readonly<{
-  type: 'commit';
-  at: number;
-  dirtyRows: readonly number[] | null;
-  planes: TerminalRenderPlanes | null;
-  focusedId: string | null;
-}>;
-type TraceStore = Readonly<{
-  enabled: Ref<boolean>;
-  records: TraceRecord[];
-  push: (record: TraceRecord) => void;
-  clear: () => void;
-  snapshot: () => TraceRecord[];
-}>;
-declare function createTraceStore(opts?: Readonly<{
-  enabled?: boolean;
-  max?: number;
-}>): TraceStore;
-
 //#endregion
 //#region src/renderer/cli/stdout-renderer.d.ts
 type CliOutput = Readonly<{
@@ -681,21 +683,22 @@ type StdoutRenderer = Readonly<{
   setCursor: (x: number, y: number) => void;
   /** Show or hide the terminal cursor */
   showCursor: (visible: boolean) => void;
-  /** Update palette/default background without recreating the renderer. */
+  /** Update default background without recreating the renderer. */
   updateTheme?: (next: Readonly<{
-    defaultBg?: AnsiColorName;
-    palette?: Partial<Record<AnsiColorName, string>>;
+    defaultBg?: string | null;
+    palette?: ThemePalette | null;
   }>) => void;
 }>;
-type StdoutColorMode = 'auto' | 'truecolor' | 'ansi256' | 'ansi16' | 'ansi8';
+type StdoutColorMode = "auto" | "truecolor" | "ansi256" | "ansi16" | "ansi8";
 declare function createStdoutRenderer(terminal: Terminal, options?: Readonly<{
   output?: CliOutput;
   clear?: boolean;
   hideCursor?: boolean;
   altScreen?: boolean;
-  /** Fallback background color when a cell has no explicit bg. */
-  defaultBg?: AnsiColorName;
-  palette?: Partial<Record<AnsiColorName, string>>;
+  /** Fallback background color when a cell has no explicit bg. `null` = transparent (terminal default). */
+  defaultBg?: string | null;
+  /** Optional ANSI-name palette used when emitting ansi256/truecolor sequences. */
+  palette?: ThemePalette | null;
   /** Track TTY resize events (process.stdout 'resize') and call terminal.resize(). */
   trackResize?: boolean;
   /** Color mode for ANSI output (auto detects truecolor via env). */
@@ -709,6 +712,94 @@ declare function createStdoutRenderer(terminal: Terminal, options?: Readonly<{
   useSyncOutput?: boolean;
 }>): StdoutRenderer;
 
+//#endregion
+//#region src/observability/trace.d.ts
+type TraceRecord = Readonly<{
+  type: "event";
+  at: number;
+  event: TerminalEventRecord;
+}> | Readonly<{
+  type: "focus";
+  at: number;
+  prev: string | null;
+  next: string | null;
+}> | Readonly<{
+  type: "commit";
+  at: number;
+  dirtyRows: readonly number[] | null;
+  planes: TerminalRenderPlanes | null;
+  sync?: boolean;
+  rendererSyncFlush?: DomRendererSyncFlushDecision | null;
+  focusedId: string | null;
+}>;
+type TraceStore = Readonly<{
+  enabled: Ref<boolean>;
+  records: TraceRecord[];
+  push: (record: TraceRecord) => void;
+  clear: () => void;
+  snapshot: () => TraceRecord[];
+}>;
+declare function createTraceStore(opts?: Readonly<{
+  enabled?: boolean;
+  max?: number;
+}>): TraceStore;
+
+//#endregion
+//#region src/observability/frame-perf.d.ts
+type FramePerfReason = "scroll" | "input" | "stream" | "resize" | "data" | "manual" | "unknown";
+type FramePerfRowBucketFallback = Readonly<{
+  plane: string;
+  reason: "dirty-ratio" | "candidate-ratio";
+  dirtyRows: number;
+  planeNodes: number;
+  candidates?: number;
+}>;
+type FramePerfMailboxFailure = Readonly<{
+  id: string;
+  queued: number;
+  dropped: number;
+}>;
+type FramePerfSample = Readonly<{
+  frameId: number;
+  reason: FramePerfReason;
+  startedAt: number;
+  durationMs: number;
+  renderManagerMs: number;
+  commitMs: number;
+  domFlushMs?: number;
+  stdoutFlushMs?: number;
+  dirtyRows: number | null;
+  activePlanes: readonly string[] | null;
+  scannedNodes: number;
+  paintedNodes: number;
+  rowBucketFallbacks?: readonly FramePerfRowBucketFallback[];
+  coalescedInvalidates: number;
+  frameTaskCount: number;
+  coalescedFrameTasks: number;
+  frameTaskQueueDepthBeforeRun: number;
+  frameTaskQueueDepthAfterRun: number;
+  remainingFrameTasks: number;
+  droppedUpdates: number;
+  mailboxFailure?: FramePerfMailboxFailure;
+  queueDepth: number;
+  liveReasons?: readonly string[];
+}>;
+declare function framePerfNow(): number;
+
+//#endregion
+//#region src/observability/frame-perf-store.d.ts
+type FramePerfStore = Readonly<{
+  enabled: Ref<boolean>;
+  acquire: (reason?: string) => () => void;
+  push: (sample: FramePerfSample) => void;
+  latest: () => FramePerfSample | null;
+  list: () => FramePerfSample[];
+  clear: () => void;
+}>;
+declare function createFramePerfStore(limit?: number, opts?: Readonly<{
+  enabled?: boolean;
+}>): FramePerfStore;
+
 //#endregion
 //#region src/vue/render/render-manager.d.ts
 type RenderRect = Readonly<{
@@ -732,13 +823,22 @@ type RenderNode = Readonly<{
   rect: RenderRect | null;
   rectY0: number;
   rectY1: number;
+  /**
+   * dirtyRows are absolute terminal rows for this node's plane.
+   * Components must ignore rows outside their rect.
+   */
   paint: (dirtyRows?: readonly number[]) => void;
 }>;
 type RenderManager = Readonly<{
   rootStack: RenderStack;
   createStack: (parent: RenderStack, zIndex: number) => RenderStack;
   invalidatePlane: (plane: TerminalRenderPlane) => void;
-  scrollPlane: (plane: TerminalRenderPlane, startY: number, endY: number, delta: number) => void;
+  /**
+   * Dangerous escape hatch: shifts whole terminal rows for the target plane, not a
+   * component-local region. Only call when the active renderer consumes terminal
+   * scrollOperations or when the caller repaints the whole affected viewport.
+   */
+  unsafeScrollPlaneRows: (plane: TerminalRenderPlane, startY: number, endY: number, delta: number) => void;
   register: (node: {
     stack: RenderStack;
     plane?: TerminalRenderPlane;
@@ -751,19 +851,40 @@ type RenderManager = Readonly<{
     plane: TerminalRenderPlane;
     zIndex: number;
     rect: RenderRect | null;
+    /**
+     * Consumed synchronously during update() and must not be retained.
+     * Callers may pass scratch arrays for hot-path invalidation.
+     * Rows are absolute terminal Y coordinates for the node's plane.
+     */
     dirtyRowsHint: readonly number[];
     paint: (dirtyRows?: readonly number[]) => void;
   }>) => void;
+  /**
+   * Hot-path dirty row marker for stable nodes. Consumed synchronously and does
+   * not replace the RenderNode object.
+   *
+   * rows are absolute terminal Y coordinates, not local component row offsets.
+   * For rect-bound nodes, rows outside the node rect are ignored.
+   */
+  markDirtyRows: (id: string, rows: readonly number[]) => boolean;
   unregister: (id: string) => void;
   render: (options?: {
     activePlanes?: TerminalRenderPlanes | null;
   }) => RenderStats | null;
 }>;
+type RowBucketFallback = Readonly<{
+  plane: TerminalRenderPlane;
+  reason: "dirty-ratio" | "candidate-ratio";
+  dirtyRows: number;
+  planeNodes: number;
+  candidates?: number;
+}>;
 type RenderStats = Readonly<{
   rows: number;
   scannedNodes: number;
   paintedNodes: number;
   candidatePlanes: readonly TerminalRenderPlane[];
+  rowBucketFallbacks?: readonly RowBucketFallback[];
 }>;
 
 //#endregion
@@ -773,15 +894,72 @@ interface LayoutContext {
   originY: number;
   clipRect: Rect | null;
 }
-type TerminalSchedulerPriority = 'high' | 'normal' | 'low';
+type TerminalSchedulerPriority = "high" | "normal" | "low";
 type TerminalSchedulerInvalidateOptions = Readonly<{
   priority?: TerminalSchedulerPriority;
   plane?: TerminalRenderPlane;
+  reason?: FramePerfReason;
+}>;
+type TerminalFrameTaskPriority = "high" | "normal" | "low";
+type TerminalFrameContext = Readonly<{
+  frameId: number;
+  startedAt: number;
+  now: () => number;
+  budgetMs: number;
+  remainingMs: () => number;
+  requestMore: () => void;
+  invalidate: (options?: TerminalSchedulerInvalidateOptions) => void;
+  /**
+   * Internal scheduler metric hook used by frame tasks/mailboxes to report
+   * dropped producer updates that were intentionally coalesced before paint.
+   *
+   * Compatibility note:
+   * TerminalFrameContext is an exported type, so additions here are public.
+   */
+  reportDroppedUpdates?: (count: number) => void;
+  reportMailboxDeliveryAttempt?: (attempt: {
+    id: string;
+    queued: number;
+    dropped: number;
+  }) => void;
+}>;
+type TerminalFrameTask = Readonly<{
+  id?: string;
+  reason?: FramePerfReason;
+  priority?: TerminalFrameTaskPriority;
+  sync?: boolean;
+  run: (ctx: TerminalFrameContext) => void;
+}>;
+type TerminalSchedulerConfig = Readonly<{
+  targetFps?: number;
+  maxFps?: number;
+  frameBudgetMs?: number;
 }>;
 type TerminalScheduler = Readonly<{
   invalidate: (options?: TerminalSchedulerInvalidateOptions) => void;
   flush: () => void;
+  /**
+   * Flushes render-manager work and requests a sync terminal commit immediately.
+   * DOM row updates may still defer to rAF when they exceed the renderer sync budget.
+   */
   flushNow: () => void;
+  configure: (options: TerminalSchedulerConfig) => void;
+  /**
+   * Queues a frame task for the next scheduler frame.
+   * false means the scheduler explicitly rejected the task; producers must clear
+   * local pending state. true or undefined means accepted so legacy schedulers
+   * that do not return a value remain valid.
+   */
+  queueFrameTask: (task: TerminalFrameTask) => boolean | void;
+  /**
+   * Best-effort cancellation for a pending id task.
+   * If the scheduler has already taken the task for the current frame,
+   * the task run() still needs to guard its own stale state.
+   */
+  cancelFrameTask?: (id: string) => boolean | void;
+  requestLive: (reason: string) => () => void;
+  dropLive: (reason: string) => void;
+  isInsideFrame: () => boolean;
 }>;
 type TerminalRuntimeHandle = Readonly<{
   update: (props: Record<string, unknown>) => void;
@@ -800,12 +978,14 @@ type ImeAnchor = Readonly<{
 }>;
 type TerminalContext = Readonly<{
   terminal: Terminal;
-  renderer: Ref<DomRenderer | null>;
+  renderer: Ref<TerminalRendererLike | null>;
+  rendererCapabilities: Ref<RendererCapabilities>;
   events: Ref<EventManager | null>;
   scheduler: TerminalScheduler;
   runtime: TerminalRuntime;
   observability: Readonly<{
     trace: TraceStore;
+    framePerf: FramePerfStore;
   }>;
   defaultStyle: Ref<Style>;
   render: RenderManager;
@@ -838,7 +1018,7 @@ type PromptSuggestion = Readonly<{
   detail?: string;
   keywords?: readonly string[];
   mentionValue?: string;
-  mentionBehavior?: 'collect' | 'inline';
+  mentionBehavior?: "collect" | "inline";
   onSelect?: (info: Readonly<{
     value: string;
     query: string;
@@ -852,14 +1032,18 @@ type TInputPluginContext = Readonly<{
     promptTrigger: string;
     promptTriggers?: readonly string[];
     promptMaxItems: number;
-    promptAlign: 'input' | 'center';
+    promptAlign: "input" | "center";
     promptSelectedStyle?: Style;
+    promptPopupStyle?: Style;
+    promptPopupBorderStyle?: Style;
+    promptPopupMatchStyle?: Style;
     mentionTrigger: string;
     mentionWorkspace: string;
     mentionMode: PathPickMode;
     mentionShowHidden: boolean;
     mentionSuggestions: readonly PromptSuggestion[];
     mentionMaxItems: number;
+    mentionChipStyle?: Style;
     collectMentions: boolean;
     mentions: readonly string[];
     skillTrigger?: string;
@@ -895,7 +1079,7 @@ type TInputPluginContext = Readonly<{
   }>) => string) => void;
   registerChipStyleProvider: (provider: Readonly<{
     getStyle: (baseStyle: Style, chip: Readonly<{
-      kind: 'multiline' | 'mention';
+      kind: "multiline" | "mention";
       absPath?: string;
     }>) => Style | null | undefined;
     version: Ref<number>;
@@ -917,11 +1101,7 @@ type TerminalApp = Readonly<{
   app: App;
   terminal: Terminal;
   events: CliEventManager;
-  scheduler: {
-    invalidate: (options?: TerminalSchedulerInvalidateOptions) => void;
-    flush: () => void;
-    flushNow: () => void;
-  };
+  scheduler: TerminalScheduler;
   defaultStyle: Ref<Style>;
   /** Returns the current IME anchor position (cursor position in cell coordinates), or null if no input is focused */
   getImeAnchor: () => ImeAnchor | null;
@@ -939,9 +1119,54 @@ type CreateTerminalAppOptions = Readonly<{
 }>;
 declare function createTerminalApp(options: CreateTerminalAppOptions): TerminalApp;
 
+//#endregion
+//#region src/observability/cli-latency.d.ts
+type StageEvent = Readonly<Record<string, unknown>> & {
+  type?: unknown;
+  key?: unknown;
+  code?: unknown;
+};
+type CliLatencyProfiler = Readonly<{
+  enabled: true;
+  recordRawInput: (info?: Readonly<{
+    bytes?: number;
+  }>) => void;
+  recordStdinDispatch: (event: StageEvent, info?: Readonly<{
+    parser?: string | null;
+  }>) => void;
+  recordEventDispatchStart: (event: StageEvent) => void;
+  recordEventDispatchEnd: (event: StageEvent, info: Readonly<{
+    defaultPrevented: boolean;
+  }>) => void;
+  recordSchedulerInvalidate: (info?: Readonly<{
+    priority?: string | null;
+    plane?: string | null;
+  }>) => void;
+  recordFlushStart: (info?: Readonly<{
+    sync?: boolean;
+    activePlanes?: readonly string[] | null;
+  }>) => void;
+  recordFlushEnd: () => void;
+  recordCommit: (info?: Readonly<{
+    sync?: boolean;
+    dirtyRows?: readonly number[] | null;
+    planes?: readonly string[] | null;
+  }>) => void;
+  recordStdoutQueued: (delayMs: number) => void;
+  recordStdoutRenderStart: () => void;
+  recordStdoutNoOutput: () => void;
+  recordStdoutWrite: (info: Readonly<{
+    durationMs: number;
+    bytes: number;
+    mode: string;
+  }>) => void;
+  markOperation: (operation: string) => void;
+}>;
+declare function getCliLatencyProfiler(): CliLatencyProfiler | null;
+
 //#endregion
 //#region src/renderer/cli/stdout-metrics.d.ts
-type StdoutRendererWriteMode = 'stream' | 'sync' | 'chunked';
+type StdoutRendererWriteMode = "stream" | "sync" | "chunked";
 interface StdoutRendererMetrics {
   lastFrameAt: number;
   lastFrameBytes: number;
@@ -955,7 +1180,7 @@ declare function getStdoutRendererMetrics(): StdoutRendererMetrics;
 
 //#endregion
 //#region src/runtime/index.d.ts
-type RuntimeEnv = 'browser' | 'terminal' | 'unknown';
+type RuntimeEnv = "browser" | "terminal" | "unknown";
 type TimerApi = Readonly<{
   setTimeout: typeof setTimeout;
   clearTimeout: typeof clearTimeout;
@@ -1011,7 +1236,7 @@ type PromptSuggestion$1 = Readonly<{
   detail?: string;
   keywords?: readonly string[];
   mentionValue?: string;
-  mentionBehavior?: 'collect' | 'inline';
+  mentionBehavior?: "collect" | "inline";
   onSelect?: (info: Readonly<{
     value: string;
     query: string;
@@ -1112,7 +1337,7 @@ declare const TInputBox: any;
 //#endregion
 //#region src/vue/components/TJsonEditor.d.ts
 type JsonLintStatus = Readonly<{
-  state: 'idle' | 'success' | 'error';
+  state: "idle" | "success" | "error";
   message?: string;
   line?: number;
   column?: number;
@@ -1166,6 +1391,10 @@ interface RenderNodeOptions {
   zIndex?: number;
   stack?: RenderStack;
   rect?: RenderRect | null;
+  /**
+   * One-shot absolute terminal rows for row-local content changes on this node's plane only.
+   * Omit this when geometry, z-order, style, data identity, or paint semantics changed.
+   */
   dirtyRowsHint?: readonly number[];
   priority?: TerminalSchedulerPriority;
   deps?: unknown;
@@ -1288,9 +1517,12 @@ interface WheelScrollResult {
   dir: -1 | 0 | 1;
   lines: number;
 }
-type WheelDeltaMode = 'auto' | 'line' | 'pixel';
+type WheelDeltaMode = "auto" | "line" | "pixel";
+interface WheelScrollOptions {
+  disableAcceleration?: boolean;
+}
 declare function createWheelScrollState(): WheelScrollState;
-declare function applyWheelScroll(state: WheelScrollState, deltaY: number, scrollTop: number, maxTop: number, now?: number, deltaMode?: WheelDeltaMode): WheelScrollResult;
+declare function applyWheelScroll(state: WheelScrollState, deltaY: number, scrollTop: number, maxTop: number, now?: number, deltaMode?: WheelDeltaMode, options?: WheelScrollOptions): WheelScrollResult;
 
 //#endregion
-export { ANSI16_COLORS, ANSI256_COLORS, ANSI8_COLORS, AnsiColorName, BufferSnapshot, Cell, CellMetrics, CliEventManager, ClipboardApi, CreateTerminalAppOptions, DomRenderer, EventManager, FsDirEntry, FsEntryKind, FsStat, LayoutContext, MentionPathProvider, MentionSuggestionProvider, PathPickMode, PathPickerProvider, PathSuggestion, PromptMentionPluginOptions, PromptSuggestion, RafApi, Rect, Runtime, RuntimeEnv, SGR_RESET, StdinDriver, StdoutRenderer, StdoutRendererMetrics, Style, SuggestPathsResult, TAnchor, TBox, TDebugOverlay, TDialog, TERMINAL_RENDER_PLANES, TFlow, TInput, TInputBox, TInputHostAdapter, TInputPlugin, TInputPluginContext, TInputPluginsContextKey, TJsonEditor, TList, TMultilineModal, TPathPicker, TRenderLayer, TRenderPlane, TRouterView, TSelect, TText, TTransition, TView, Terminal, TerminalApp, TerminalBaseEvent, TerminalColorCapability, TerminalColorLevel, TerminalColorMode, TerminalCommitEvent, TerminalContext, TerminalDebugNode, TerminalEventHandlerMap, TerminalEventMap, TerminalEventRecord, TerminalEventType, TerminalInputEvent, TerminalKeyboardEvent, TerminalNode, TerminalPointerEvent, TerminalProvider, TerminalRenderPlane, TerminalRenderPlanes, TerminalResizeEvent, TerminalRoute, TerminalRouteLocationRaw, TerminalRouteRecord, TerminalRouter, TerminalRuntime, TerminalRuntimeHandle, TerminalScheduler, TerminalSchedulerInvalidateOptions, TerminalScrollOperation, TimerApi, TraceRecord, TraceStore, ansiColors, ansiStyles, applyWheelScroll, charCellWidth, clearTextCaches, createCliEventManager, createDefaultTInputHostAdapter, createDomRenderer, createEventManager, createNodeMentionPathProvider, createNodePathPickerProvider, createPromptMentionPlugin, createRuntime, createStdinDriver, createStdoutRenderer, createTInputHostPlugin, createTerminal, createTerminalApp, createTerminalRouter, createTextRestrictionPlugin, createTraceStore, createWheelScrollState, defaultTInputHostPlugin, detectTerminalColorCapability, formatInlineCellLine, getStdoutRendererMetrics, lintJsonText, normalizeNewlines, padEndByCells, parseAnsiSgr, readEventLog, resolveUserPath, rgbToAnsi256, sanitizeInlineText, sanitizeTextBlock, sliceByCells, sliceByCellsRange, spaces, suggestPaths, textCellWidth, truecolorBgOpen, truecolorFgOpen, useLayout, useRenderNode, useRoute, useRouter, useTerminal, useTerminalNode, useTerminalRuntime, useVisibility, wrapByCells, writeEventLog, writeSnapshot };
+export { ANSI16_COLORS, ANSI256_COLORS, ANSI8_COLORS, AnsiColorName, BufferSnapshot, Cell, CellMetrics, CliEventManager, ClipboardApi, CreateTerminalAppOptions, DOM_RENDERER_CAPABILITIES, DomRenderer, DomRendererDebugStats, DomRendererFlushSample, DomRendererFlushStats, DomRendererOptions, DomRendererRowKeyPrepassDebugStats, DomRendererRowKeyPrepassDecision, DomRendererRowKeyPrepassMode, DomRendererRowRenderDebugStats, DomRendererRowRenderStats, DomRendererSyncFlushDecision, DomRendererSyncFlushStats, EventManager, FramePerfReason, FramePerfRowBucketFallback, FramePerfSample, FramePerfStore, FsDirEntry, FsEntryKind, FsStat, HEADLESS_RENDERER_CAPABILITIES, LayoutContext, MentionPathProvider, MentionSuggestionProvider, PathPickMode, PathPickerProvider, PathSuggestion, PromptMentionPluginOptions, PromptSuggestion, RafApi, Rect, RendererCapabilities, Runtime, RuntimeEnv, SGR_RESET, StdinDriver, StdoutRenderer, StdoutRendererMetrics, Style, SuggestPathsResult, TAnchor, TBox, TDebugOverlay, TDialog, TERMINAL_RENDER_PLANES, TFlow, TInput, TInputBox, TInputHostAdapter, TInputPlugin, TInputPluginContext, TInputPluginsContextKey, TJsonEditor, TList, TMultilineModal, TPathPicker, TRenderLayer, TRenderPlane, TRouterView, TSelect, TText, TTransition, TView, Terminal, TerminalApp, TerminalBaseEvent, TerminalColorCapability, TerminalColorLevel, TerminalColorMode, TerminalCommitEvent, TerminalContext, TerminalDebugNode, TerminalEventHandlerMap, TerminalEventMap, TerminalEventRecord, TerminalEventType, TerminalFrameContext, TerminalFrameTask, TerminalFrameTaskPriority, TerminalInputEvent, TerminalKeyboardEvent, TerminalNode, TerminalPointerEvent, TerminalProvider, TerminalRenderPlane, TerminalRenderPlanes, TerminalRendererLike, TerminalResizeEvent, TerminalRoute, TerminalRouteLocationRaw, TerminalRouteRecord, TerminalRouter, TerminalRuntime, TerminalRuntimeHandle, TerminalScheduler, TerminalSchedulerConfig, TerminalSchedulerInvalidateOptions, TerminalScrollOperation, ThemeModeId, ThemePalette, TimerApi, TraceRecord, TraceStore, TuiMarkdownTheme, TuiMarkdownThemeOverrides, ansiColors, ansiStyles, applyWheelScroll, charCellWidth, clearTextCaches, createCliEventManager, createDefaultTInputHostAdapter, createDomRenderer, createEventManager, createFramePerfStore, createNodeMentionPathProvider, createNodePathPickerProvider, createPromptMentionPlugin, createRuntime, createStdinDriver, createStdoutRenderer, createTInputHostPlugin, createTerminal, createTerminalApp, createTerminalRouter, createTextRestrictionPlugin, createTraceStore, createWheelScrollState, defaultTInputHostPlugin, detectTerminalColorCapability, formatInlineCellLine, framePerfNow, getCliLatencyProfiler, getStdoutRendererMetrics, lintJsonText, normalizeNewlines, padEndByCells, parseAnsiSgr, readEventLog, resolveUserPath, rgbToAnsi256, sanitizeInlineText, sanitizeTextBlock, sliceByCells, sliceByCellsRange, spaces, suggestPaths, textCellWidth, truecolorBgOpen, truecolorFgOpen, useLayout, useRenderNode, useRoute, useRouter, useTerminal, useTerminalNode, useTerminalRuntime, useVisibility, wrapByCells, writeEventLog, writeSnapshot };