feat: add virtual list sticky-follow mode, tool approval dialog (#405)

* feat: add virtual list sticky-follow mode, tool approval dialog event blocking, and max blob size configuration

* feat: add render request mechanism for tool approvals and refine sticky scrolling logic for list tails

* fix: finalize sticky follow dialog merge checks

---------

Co-authored-by: RtlZeroMemory <58250858+RtlZeroMemory@users.noreply.github.com>

Author: Gastroam

CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on Keep a Changelog and the project follows Semantic Version
 
 ## [Unreleased]
 
+### Added
+
+- **core/virtual-list**: Added `ensureVisibleIndex` with sticky follow mode for log and chat tail-follow behavior.
+- **core/tool-approval**: Added the tool approval dialog modal surface and mouse action routing.
+- **core/rendering**: Added `maxBlobBytes` app config for drawlist blob payload limits.
+
+### Documentation
+
+- Documented virtual list sticky follow behavior, tool approval dialog modal input behavior, and `maxBlobBytes` engine config.
+
 ## [0.1.0-alpha.71] - 2026-04-27
 
 ### Documentation

docs/backend/engine-config.md

@@ -14,6 +14,7 @@ const app = createNodeApp({
   config: {
     fpsCap: 30,
     maxDrawlistBytes: 4 << 20, // 4 MiB
+    maxBlobBytes: 1 << 20, // 1 MiB
     drawlistValidateParams: false, // trusted inputs, skip validation
     maxFramesInFlight: 2,
   },
@@ -27,10 +28,18 @@ type AppConfig = Readonly<{
   fpsCap?: number;
   maxEventBytes?: number;
   maxDrawlistBytes?: number;
+  maxBlobBytes?: number;
+  rootPadding?: number;
+  breakpoints?: Readonly<{
+    smMax?: number;
+    mdMax?: number;
+    lgMax?: number;
+  }>;
   drawlistValidateParams?: boolean;
   drawlistReuseOutputBuffer?: boolean;
   drawlistEncodedStringCacheCap?: number;
   maxFramesInFlight?: number;
+  themeTransitionFrames?: number;
   internal_onRender?: (metrics: AppRenderMetrics) => void;
   internal_onLayout?: (snapshot: AppLayoutSnapshot) => void;
 }>;
@@ -86,6 +95,24 @@ config: {
 }
 ```
 
+### maxBlobBytes
+
+| Detail   | Value |
+|----------|-------|
+| Type     | `number` (positive integer) |
+| Default  | `512 << 10` (512 KiB) |
+
+Maximum total byte size of the drawlist blob pool for a frame. If binary payloads
+exceed this limit during frame construction, the frame is rejected. Increase this
+value only for applications that intentionally render large binary-backed
+surfaces such as images or canvases.
+
+```typescript
+config: {
+  maxBlobBytes: 1 << 20, // 1 MiB blob pool
+}
+```
+
 ### drawlistValidateParams
 
 | Detail   | Value |
@@ -129,7 +156,7 @@ remains safe regardless of the pipelining depth.
 | Detail   | Value |
 |----------|-------|
 | Type     | `number` (non-negative integer) |
-| Default  | `1024` |
+| Default  | `131072` |
 
 Maximum number of UTF-8 encoded strings to cache across frames. The drawlist
 builder maintains a cache of encoded strings to avoid redundant
@@ -142,7 +169,7 @@ application renders many unique but repeated strings across frames.
 
 ```typescript
 config: {
-  drawlistEncodedStringCacheCap: 2048, // larger cache for text-heavy UIs
+  drawlistEncodedStringCacheCap: 262144, // larger cache for text-heavy UIs
 }
 ```
 
@@ -177,10 +204,13 @@ config: {
 | `fpsCap`                        | `60`          |
 | `maxEventBytes`                 | `1048576` (1 MiB) |
 | `maxDrawlistBytes`              | `2097152` (2 MiB) |
+| `maxBlobBytes`                  | `524288` (512 KiB) |
+| `rootPadding`                   | `0`           |
 | `drawlistValidateParams`        | `true` (app runtime default) |
 | `drawlistReuseOutputBuffer`     | `true`        |
-| `drawlistEncodedStringCacheCap` | `1024`        |
+| `drawlistEncodedStringCacheCap` | `131072`      |
 | `maxFramesInFlight`             | `1`           |
+| `themeTransitionFrames`         | `0`           |
 
 ## See Also
 

docs/widgets/tool-approval-dialog.md

@@ -37,6 +37,8 @@ ui.toolApprovalDialog({
 - `ToolRequest` includes metadata like `toolId`, `toolName`, `riskLevel`, and optional `fileChanges`.
 - `fileChanges` entries include `path`, `changeType`, and optional `preview`/`oldPath` for renames.
 - Default dialog size is `50x15` cells when `width`/`height` are omitted.
+- When open, the dialog is a modal layer with a dim backdrop.
+- Backdrop clicks and clicks behind the dialog are blocked; only the dialog action regions route mouse presses.
 
 ## Related
 

docs/widgets/virtual-list.md

@@ -48,6 +48,8 @@ ui.virtualList({
 | `measureItemHeight` | `(item, index, ctx) => number` | internal measurer | Optional custom measurement callback for estimate mode |
 | `renderItem` | `(item, index, focused) => VNode` | **required** | Render function for each item |
 | `overscan` | `number` | `3` | Extra items rendered above/below viewport |
+| `ensureVisibleIndex` | `number` | - | Item index to keep visible after render, useful for tail-following logs or chat |
+| `ensureVisibleMode` | `"always" \| "sticky"` | `"always"` | Whether `ensureVisibleIndex` always repositions or follows only while attached |
 | `keyboardNavigation` | `boolean` | `true` | Enable arrow/page/home/end navigation |
 | `wrapAround` | `boolean` | `false` | Wrap selection from end to start |
 | `scrollDirection` | `"traditional" \| "natural"` | `"traditional"` | Mouse-wheel direction mode for this list |
@@ -62,6 +64,9 @@ ui.virtualList({
 - **Mouse scroll wheel** scrolls the list (3 lines per tick).
   - `scrollDirection: "traditional"` (default): wheel down moves viewport down.
   - `scrollDirection: "natural"`: wheel down moves content down (trackpad-style).
+- `ensureVisibleIndex` keeps a target item visible after render.
+  - `ensureVisibleMode: "always"` scrolls whenever the target is outside the viewport.
+  - `ensureVisibleMode: "sticky"` follows the target only while the user remains attached.
 - The `onScroll` callback fires for both keyboard navigation and mouse wheel input.
 
 ## Notes
@@ -72,6 +77,8 @@ ui.virtualList({
 - Returned `measureItemHeight` values are normalized before entering the measured-height cache: non-finite or non-positive values fall back to `estimatedHeight`, and positive values are truncated to whole cells with a minimum of 1.
 - In estimate mode, visible items are measured and cached, then scroll math is corrected on the following frame.
 - Measured-height cache is reused only while viewport width and item count stay the same; changing either triggers remeasurement.
+- Sticky follow is disabled when keyboard or wheel input moves away from the target, and re-enabled when the viewport reaches the target again.
+- Oversized sticky targets anchor their bottom edge to avoid scroll oscillation.
 - `renderItem` receives a `focused` flag for styling.
 - `selectionStyle` still applies to the selected row in estimate mode.
 - The `range` passed to `onScroll` is `[startIndex, endIndex)` and includes overscan.

packages/core/etc/core.api.md

@@ -160,6 +160,7 @@ export type AppConfig = Readonly<{
     fpsCap?: number;
     maxEventBytes?: number;
     maxDrawlistBytes?: number;
+    maxBlobBytes?: number;
     rootPadding?: number;
     breakpoints?: Readonly<{
         smMax?: number;
@@ -7375,6 +7376,7 @@ export type VirtualListLocalState = Readonly<{
     viewportHeight: number;
     startIndex: number;
     endIndex: number;
+    stickyFollowActive?: boolean;
     measuredHeights?: ReadonlyMap<number, number>;
     measuredWidth?: number;
     measuredItemCount?: number;
@@ -7387,6 +7389,7 @@ export type VirtualListLocalStatePatch = Readonly<{
     viewportHeight?: number;
     startIndex?: number;
     endIndex?: number;
+    stickyFollowActive?: boolean;
     measuredHeights?: ReadonlyMap<number, number>;
     measuredWidth?: number;
     measuredItemCount?: number;
@@ -7411,6 +7414,8 @@ export type VirtualListProps<T = unknown> = Readonly<{
     measureItemHeight?: (item: T, index: number, ctx: VirtualListMeasureItemHeightCtx) => number;
     overscan?: number;
     renderItem: (item: T, index: number, focused: boolean) => VNode;
+    ensureVisibleIndex?: number;
+    ensureVisibleMode?: "always" | "sticky";
     onScroll?: (scrollTop: number, visibleRange: [number, number]) => void;
     onSelect?: (item: T, index: number) => void;
     keyboardNavigation?: boolean;
@@ -8016,8 +8021,8 @@ export type ZrUiErrorCode = "ZRUI_INVALID_STATE" | "ZRUI_MODE_CONFLICT" | "ZRUI_
 // src/runtime/instances.ts:56:3 - (ae-forgotten-export) The symbol "UnknownCallback_2" needs to be exported by the entry point index.d.ts
 // src/runtime/instances.ts:134:3 - (ae-forgotten-export) The symbol "InstanceId" needs to be exported by the entry point index.d.ts
 // src/runtime/instances.ts:161:3 - (ae-forgotten-export) The symbol "AppStateSelection" needs to be exported by the entry point index.d.ts
-// src/runtime/localState.ts:401:3 - (ae-forgotten-export) The symbol "TreeFlatCache" needs to be exported by the entry point index.d.ts
-// src/runtime/localState.ts:406:3 - (ae-forgotten-export) The symbol "TreePrefixCache" needs to be exported by the entry point index.d.ts
+// src/runtime/localState.ts:412:3 - (ae-forgotten-export) The symbol "TreeFlatCache" needs to be exported by the entry point index.d.ts
+// src/runtime/localState.ts:417:3 - (ae-forgotten-export) The symbol "TreePrefixCache" needs to be exported by the entry point index.d.ts
 // src/runtime/widgetMeta/focusInfo.ts:8:3 - (ae-forgotten-export) The symbol "RuntimeInstance" needs to be exported by the entry point index.d.ts
 // src/testing/renderer.ts:93:3 - (ae-forgotten-export) The symbol "TestRecordedOp" needs to be exported by the entry point index.d.ts
 // src/widgets/composition.ts:88:3 - (ae-forgotten-export) The symbol "UnknownCallback" needs to be exported by the entry point index.d.ts

packages/core/src/app/__tests__/widgetBehavior.contracts.test.ts

@@ -475,6 +475,144 @@ describe("modal, overlay, and focus behavior contracts", () => {
     assert.equal(renderer.getFocusedId(), "cancel");
   });
 
+  test("tool approval dialog mouse clicks activate action regions", () => {
+    const renderer = new WidgetRenderer<void>({
+      backend: createNoopBackend(),
+      requestRender: () => {},
+    });
+
+    let open = true;
+    let allowSessionCount = 0;
+    let closeCount = 0;
+    const view = () =>
+      ui.layers([
+        ui.button({ id: "background", label: "Background action" }),
+        ...(open
+          ? [
+              ui.toolApprovalDialog({
+                id: "approval",
+                open: true,
+                request: {
+                  toolId: "terminal",
+                  toolName: "terminal",
+                  command: "rm -rf ./dist",
+                  riskLevel: "high",
+                },
+                onPress: () => {},
+                onAllowForSession: () => {
+                  allowSessionCount++;
+                },
+                onClose: () => {
+                  closeCount++;
+                  open = false;
+                },
+              }),
+            ]
+          : []),
+      ]);
+
+    submit(renderer, view, { cols: 80, rows: 24 });
+    const rect = renderer.getRectByIdIndex().get("approval");
+    assert.ok(rect !== undefined, "approval rect should exist");
+    if (!rect) return;
+
+    const x = rect.x + 22;
+    const y = rect.y + rect.h - 2;
+    renderer.routeEngineEvent(mouseEvent(x, y, 3, { buttons: 1 }));
+    renderer.routeEngineEvent(mouseEvent(x, y, 4));
+
+    assert.equal(renderer.getFocusedId(), "approval");
+    assert.equal(allowSessionCount, 1);
+    assert.equal(closeCount, 1);
+  });
+
+  test("tool approval dialog blocks backdrop clicks from background widgets", () => {
+    const renderer = new WidgetRenderer<void>({
+      backend: createNoopBackend(),
+      requestRender: () => {},
+    });
+
+    let backgroundPresses = 0;
+    const view = () =>
+      ui.layers([
+        ui.button({
+          id: "background",
+          label: "Background action",
+          onPress: () => {
+            backgroundPresses++;
+          },
+        }),
+        ui.toolApprovalDialog({
+          id: "approval",
+          open: true,
+          request: {
+            toolId: "terminal",
+            toolName: "terminal",
+            command: "rm -rf ./dist",
+            riskLevel: "high",
+          },
+          onPress: () => {},
+          onClose: () => {},
+        }),
+      ]);
+
+    submit(renderer, view, { cols: 80, rows: 24 });
+    const bgCenter = centerOf(renderer, "background");
+    renderer.routeEngineEvent(mouseEvent(bgCenter.x, bgCenter.y, 3, { buttons: 1 }));
+    renderer.routeEngineEvent(mouseEvent(bgCenter.x, bgCenter.y, 4));
+
+    assert.equal(backgroundPresses, 0);
+  });
+
+  test("tool approval dialog keeps backdrop blocking after layout-only resize", () => {
+    const renderer = new WidgetRenderer<void>({
+      backend: createNoopBackend(),
+      requestRender: () => {},
+    });
+
+    let backgroundPresses = 0;
+    const view = () =>
+      ui.layers([
+        ui.button({
+          id: "background",
+          label: "Background action",
+          onPress: () => {
+            backgroundPresses++;
+          },
+        }),
+        ui.toolApprovalDialog({
+          id: "approval",
+          open: true,
+          request: {
+            toolId: "terminal",
+            toolName: "terminal",
+            command: "rm -rf ./dist",
+            riskLevel: "high",
+          },
+          onPress: () => {},
+          onClose: () => {},
+        }),
+      ]);
+
+    submit(renderer, view, { cols: 80, rows: 24 });
+
+    const resized = renderer.submitFrame(
+      view,
+      undefined,
+      { cols: 100, rows: 24 },
+      defaultTheme,
+      noRenderHooks(),
+      { commit: false, layout: true, checkLayoutStability: false },
+    );
+    assert.equal(resized.ok, true, "layout-only frame should render");
+
+    const bgCenter = centerOf(renderer, "background");
+    renderer.routeEngineEvent(mouseEvent(bgCenter.x, bgCenter.y, 3, { buttons: 1 }));
+    renderer.routeEngineEvent(mouseEvent(bgCenter.x, bgCenter.y, 4));
+
+    assert.equal(backgroundPresses, 0);
+  });
+
   test("top layer above a modal still receives mouse presses", () => {
     const renderer = new WidgetRenderer<void>({
       backend: createNoopBackend(),

packages/core/src/app/createApp.ts

@@ -375,6 +375,7 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
   const rawRenderer = new RawRenderer({
     backend,
     maxDrawlistBytes: config.maxDrawlistBytes,
+    maxBlobBytes: config.maxBlobBytes,
     ...(opts.config?.drawlistValidateParams === undefined
       ? {}
       : { drawlistValidateParams: opts.config.drawlistValidateParams }),
@@ -384,6 +385,7 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
   const widgetRenderer = new WidgetRenderer<S>({
     backend,
     maxDrawlistBytes: config.maxDrawlistBytes,
+    maxBlobBytes: config.maxBlobBytes,
     rootPadding: config.rootPadding,
     breakpointThresholds: config.breakpointThresholds,
     terminalProfile,

packages/core/src/app/createApp/config.ts

@@ -20,6 +20,7 @@ export type ResolvedAppConfig = Readonly<{
   fpsCap: number;
   maxEventBytes: number;
   maxDrawlistBytes: number;
+  maxBlobBytes: number;
   rootPadding: number;
   breakpointThresholds: ResponsiveBreakpointThresholds;
   drawlistValidateParams: boolean;
@@ -35,6 +36,7 @@ const DEFAULT_CONFIG: ResolvedAppConfig = Object.freeze({
   fpsCap: 60,
   maxEventBytes: 1 << 20 /* 1 MiB */,
   maxDrawlistBytes: 2 << 20 /* 2 MiB */,
+  maxBlobBytes: 512 << 10 /* 512 KiB */,
   rootPadding: 0,
   breakpointThresholds: normalizeBreakpointThresholds(undefined),
   drawlistValidateParams: true,
@@ -83,6 +85,10 @@ export function resolveAppConfig(config: AppConfig | undefined): ResolvedAppConf
     config.maxDrawlistBytes === undefined
       ? DEFAULT_CONFIG.maxDrawlistBytes
       : requirePositiveInt("maxDrawlistBytes", config.maxDrawlistBytes);
+  const maxBlobBytes =
+    config.maxBlobBytes === undefined
+      ? DEFAULT_CONFIG.maxBlobBytes
+      : requirePositiveInt("maxBlobBytes", config.maxBlobBytes);
   const rootPadding =
     config.rootPadding === undefined
       ? DEFAULT_CONFIG.rootPadding
@@ -120,6 +126,7 @@ export function resolveAppConfig(config: AppConfig | undefined): ResolvedAppConf
     fpsCap,
     maxEventBytes,
     maxDrawlistBytes,
+    maxBlobBytes,
     rootPadding,
     breakpointThresholds,
     drawlistValidateParams,

packages/core/src/app/rawRenderer.ts

@@ -51,6 +51,7 @@ export class RawRenderer {
       backend: RuntimeBackend;
       builder?: DrawlistBuilder;
       maxDrawlistBytes?: number;
+      maxBlobBytes?: number;
       drawlistValidateParams?: boolean;
       drawlistReuseOutputBuffer?: boolean;
       drawlistEncodedStringCacheCap?: number;
@@ -59,6 +60,7 @@ export class RawRenderer {
     this.backend = opts.backend;
     const builderOpts = {
       ...(opts.maxDrawlistBytes === undefined ? {} : { maxDrawlistBytes: opts.maxDrawlistBytes }),
+      ...(opts.maxBlobBytes === undefined ? {} : { maxBlobBytes: opts.maxBlobBytes }),
       ...(opts.drawlistValidateParams === undefined
         ? {}
         : { validateParams: opts.drawlistValidateParams }),