@rezi-ui/core 0.1.0-alpha.7 → 0.1.0-alpha.70

package/dist/renderer/renderToDrawlist/widgets/containers.js

@@ -1,29 +1,132 @@
-import { createShadowConfig, renderShadow } from "../../shadow.js";
+import { modalRecipe, surfaceRecipe } from "../../../ui/recipes.js";
+import { SCROLLBAR_CONFIGS, renderHorizontalScrollbar, renderVerticalScrollbar, } from "../../scrollbar.js";
+import { renderShadow, resolveBoxShadowConfig } from "../../shadow.js";
 import { asTextStyle } from "../../styles.js";
 import { readBoxBorder, readTitleAlign, renderBoxBorder } from "../boxBorder.js";
+import { getRuntimeNodeDamageRect } from "../damageBounds.js";
 import { isVisibleRect } from "../indices.js";
 import { clampNonNegative, resolveSpacingFromProps } from "../spacing.js";
-import { mergeTextStyle, shouldFillForStyleOverride } from "../textStyle.js";
+import { applyOpacityToStyle, mergeTextStyle, shouldFillForStyleOverride } from "../textStyle.js";
+import { getColorTokens } from "../themeTokens.js";
+const SCROLLBAR_RENDER_CONFIG = {
+    ...SCROLLBAR_CONFIGS.minimal,
+    minThumbSize: 1,
+};
+function readScrollbarVariant(raw) {
+    switch (raw) {
+        case "classic":
+        case "modern":
+        case "dots":
+        case "thin":
+            return raw;
+        default:
+            return "minimal";
+    }
+}
+function readBorderSideStyleMap(raw, theme) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const source = raw;
+    const top = asTextStyle(source.top, theme);
+    const right = asTextStyle(source.right, theme);
+    const bottom = asTextStyle(source.bottom, theme);
+    const left = asTextStyle(source.left, theme);
+    if (!top && !right && !bottom && !left)
+        return undefined;
+    return {
+        ...(top ? { top } : {}),
+        ...(right ? { right } : {}),
+        ...(bottom ? { bottom } : {}),
+        ...(left ? { left } : {}),
+    };
+}
+function readSurfacePreset(raw) {
+    switch (raw) {
+        case "surface":
+        case "card":
+        case "well":
+        case "elevated":
+            return raw;
+        default:
+            return undefined;
+    }
+}
+function resolveSurfacePresetConfig(raw) {
+    const preset = readSurfacePreset(raw);
+    switch (preset) {
+        case "surface":
+            return { elevation: 0, cardLike: false };
+        case "card":
+            return { elevation: 1, cardLike: true };
+        case "well":
+            return { elevation: 1, cardLike: false };
+        case "elevated":
+            return { elevation: 2, cardLike: true };
+        default:
+            return undefined;
+    }
+}
+function mergeBorderSideStyles(base, override) {
+    if (!base && !override)
+        return undefined;
+    return {
+        ...(base?.top ? { top: base.top } : {}),
+        ...(base?.right ? { right: base.right } : {}),
+        ...(base?.bottom ? { bottom: base.bottom } : {}),
+        ...(base?.left ? { left: base.left } : {}),
+        ...(override?.top ? { top: override.top } : {}),
+        ...(override?.right ? { right: override.right } : {}),
+        ...(override?.bottom ? { bottom: override.bottom } : {}),
+        ...(override?.left ? { left: override.left } : {}),
+    };
+}
 function clipEquals(a, b) {
     return a !== undefined && a.x === b.x && a.y === b.y && a.w === b.w && a.h === b.h;
 }
+/**
+ * Returns a callback that pushes clip + pop-sentinel exactly when the first
+ * renderable child is queued. This avoids emitting no-op clip ops when
+ * damage-culling leaves a container with zero queued children.
+ */
+function clipOnFirstQueuedChild(builder, nodeStack, currentClip, childClip) {
+    if (!childClip || clipEquals(currentClip, childClip))
+        return undefined;
+    return () => {
+        builder.pushClip(childClip.x, childClip.y, childClip.w, childClip.h);
+        // Push sentinel before the first child so pop runs after subtree render.
+        nodeStack.push(null);
+    };
+}
 function rectIntersects(a, b) {
     if (a.w <= 0 || a.h <= 0 || b.w <= 0 || b.h <= 0)
         return false;
     return a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
 }
-function findStackChildRange(children, childCount, direction, damageRect) {
+function usesVisibleOverflow(node) {
+    const kind = node.vnode.kind;
+    if (kind !== "row" && kind !== "column" && kind !== "grid" && kind !== "box") {
+        return false;
+    }
+    if (node.children.length === 0) {
+        return false;
+    }
+    const props = node.vnode.props;
+    return props.overflow !== "hidden" && props.overflow !== "scroll";
+}
+function findStackChildRange(runtimeChildren, children, childCount, direction, damageRect) {
     const damageStart = direction === "column" ? damageRect.y : damageRect.x;
     const damageEnd = direction === "column" ? damageRect.y + damageRect.h : damageRect.x + damageRect.w;
     let start = 0;
     while (start < childCount) {
+        const runtimeChild = runtimeChildren[start];
         const child = children[start];
-        if (!child) {
+        if (!runtimeChild || !child) {
             start++;
             continue;
         }
-        const childStart = direction === "column" ? child.rect.y : child.rect.x;
-        const childSize = direction === "column" ? child.rect.h : child.rect.w;
+        const childRect = getRuntimeNodeDamageRect(runtimeChild, child.rect);
+        const childStart = direction === "column" ? childRect.y : childRect.x;
+        const childSize = direction === "column" ? childRect.h : childRect.w;
         const childEnd = childStart + childSize;
         if (childEnd > damageStart)
             break;
@@ -33,12 +136,14 @@ function findStackChildRange(children, childCount, direction, damageRect) {
         return null;
     let endExclusive = start;
     while (endExclusive < childCount) {
+        const runtimeChild = runtimeChildren[endExclusive];
         const child = children[endExclusive];
-        if (!child) {
+        if (!runtimeChild || !child) {
             endExclusive++;
             continue;
         }
-        const childStart = direction === "column" ? child.rect.y : child.rect.x;
+        const childRect = getRuntimeNodeDamageRect(runtimeChild, child.rect);
+        const childStart = direction === "column" ? childRect.y : childRect.x;
         if (childStart >= damageEnd)
             break;
         endExclusive++;
@@ -47,102 +152,270 @@ function findStackChildRange(children, childCount, direction, damageRect) {
         return null;
     return { start, end: endExclusive - 1 };
 }
-function pushChildrenWithLayout(node, layoutNode, style, nodeStack, styleStack, layoutStack, clipStack, clip, damageRect, stackDirection = undefined) {
+function pushChildrenWithLayout(node, layoutNode, style, nodeStack, styleStack, layoutStack, clipStack, clip, damageRect, skipCleanSubtrees, forceSubtreeRender, stackDirection = undefined, onFirstQueuedChild = undefined) {
     const childCount = Math.min(node.children.length, layoutNode.children.length);
     if (childCount <= 0)
-        return;
+        return 0;
     let rangeStart = 0;
     let rangeEnd = childCount - 1;
     if (damageRect) {
         if (stackDirection) {
-            const range = findStackChildRange(layoutNode.children, childCount, stackDirection, damageRect);
-            if (!range)
-                return;
-            rangeStart = range.start;
-            rangeEnd = range.end;
+            let hasVisibleOverflowChild = false;
+            for (let i = 0; i < childCount; i++) {
+                const child = node.children[i];
+                if (child && usesVisibleOverflow(child)) {
+                    hasVisibleOverflowChild = true;
+                    break;
+                }
+            }
+            if (!hasVisibleOverflowChild) {
+                const range = findStackChildRange(node.children, layoutNode.children, childCount, stackDirection, damageRect);
+                if (!range)
+                    return 0;
+                rangeStart = range.start;
+                rangeEnd = range.end;
+            }
         }
     }
+    let pushedChildren = 0;
     for (let i = rangeEnd; i >= rangeStart; i--) {
         const c = node.children[i];
         const lc = layoutNode.children[i];
-        if (c && lc && (!damageRect || rectIntersects(lc.rect, damageRect))) {
+        const childCanOverflow = c ? usesVisibleOverflow(c) : false;
+        if (c &&
+            lc &&
+            (!skipCleanSubtrees || forceSubtreeRender || c.dirty) &&
+            (!damageRect ||
+                childCanOverflow ||
+                rectIntersects(getRuntimeNodeDamageRect(c, lc.rect), damageRect))) {
+            if (pushedChildren === 0) {
+                onFirstQueuedChild?.();
+            }
+            if (forceSubtreeRender) {
+                c.dirty = true;
+                if (c.children.length > 0)
+                    c.selfDirty = true;
+            }
             nodeStack.push(c);
             styleStack.push(style);
             layoutStack.push(lc);
             clipStack.push(clip);
+            pushedChildren++;
         }
     }
+    return pushedChildren;
+}
+function readRgbColor(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+        return undefined;
+    }
+    return (Math.round(raw) >>> 0) & 0x00ff_ffff;
 }
-function readShadowDensity(raw) {
-    if (raw === "light" || raw === "medium" || raw === "dense") {
+function readOverlayFrameColors(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        return {};
+    }
+    const frame = raw;
+    const foreground = readRgbColor(frame.foreground);
+    const background = readRgbColor(frame.background);
+    const border = readRgbColor(frame.border);
+    return {
+        ...(foreground !== undefined ? { foreground } : {}),
+        ...(background !== undefined ? { background } : {}),
+        ...(border !== undefined ? { border } : {}),
+    };
+}
+function toOverlaySurfaceStyle(frame) {
+    if (frame.foreground === undefined && frame.background === undefined) {
+        return undefined;
+    }
+    return {
+        ...(frame.foreground !== undefined ? { fg: frame.foreground } : {}),
+        ...(frame.background !== undefined ? { bg: frame.background } : {}),
+    };
+}
+function readBackdropVariant(raw, fallback) {
+    if (raw === "none" || raw === "dim" || raw === "opaque") {
         return raw;
     }
-    return undefined;
+    return fallback;
 }
-function readShadowOffset(raw, fallback) {
-    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+function readBackdropPattern(raw, fallback) {
+    if (typeof raw !== "string") {
+        return fallback;
+    }
+    const first = Array.from(raw)[0];
+    if (first === undefined || first.length === 0) {
         return fallback;
     }
-    const value = Math.trunc(raw);
-    return value <= 0 ? 0 : value;
+    return first;
 }
-function resolveBoxShadowConfig(shadow, theme) {
-    if (shadow !== true && (shadow === false || shadow === undefined || shadow === null)) {
-        return null;
+function resolveModalBackdrop(raw) {
+    if (raw === "none" || raw === "dim" || raw === "opaque") {
+        return { variant: raw, pattern: "░" };
     }
-    if (shadow === true) {
-        return createShadowConfig({ color: theme.colors.border });
+    if (typeof raw !== "object" || raw === null) {
+        return { variant: "dim", pattern: "░" };
     }
-    if (typeof shadow !== "object") {
-        return null;
+    const config = raw;
+    const foreground = readRgbColor(config.foreground ?? config.fg);
+    const background = readRgbColor(config.background ?? config.bg);
+    return {
+        variant: readBackdropVariant(config.variant ?? config.style, "dim"),
+        pattern: readBackdropPattern(config.pattern, "░"),
+        ...(foreground !== undefined ? { foreground } : {}),
+        ...(background !== undefined ? { background } : {}),
+    };
+}
+function clampNonNegativeInt(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return 0;
+    const n = Math.trunc(raw);
+    return n <= 0 ? 0 : n;
+}
+function readOverflowMode(raw) {
+    if (raw === "hidden" || raw === "scroll") {
+        return raw;
     }
-    const config = shadow;
-    const offsetX = readShadowOffset(config.offsetX, 1);
-    const offsetY = readShadowOffset(config.offsetY, 1);
-    const density = readShadowDensity(config.density);
-    if (offsetX <= 0 && offsetY <= 0) {
-        return null;
+    return "visible";
+}
+function readOverflowMetadata(layoutNode, contentRect) {
+    const meta = layoutNode.meta;
+    const viewportWidth = clampNonNegativeInt(meta?.viewportWidth) || contentRect.w;
+    const viewportHeight = clampNonNegativeInt(meta?.viewportHeight) || contentRect.h;
+    const contentWidth = Math.max(clampNonNegativeInt(meta?.contentWidth), viewportWidth);
+    const contentHeight = Math.max(clampNonNegativeInt(meta?.contentHeight), viewportHeight);
+    const maxScrollX = Math.max(0, contentWidth - viewportWidth);
+    const maxScrollY = Math.max(0, contentHeight - viewportHeight);
+    return {
+        scrollX: Math.min(clampNonNegativeInt(meta?.scrollX), maxScrollX),
+        scrollY: Math.min(clampNonNegativeInt(meta?.scrollY), maxScrollY),
+        contentWidth,
+        contentHeight,
+        viewportWidth,
+        viewportHeight,
+    };
+}
+function resolveScrollViewport(contentRect, meta) {
+    let showVertical = meta.contentHeight > contentRect.h;
+    let showHorizontal = meta.contentWidth > contentRect.w;
+    for (let i = 0; i < 2; i++) {
+        const nextViewportW = clampNonNegative(contentRect.w - (showVertical ? 1 : 0));
+        const nextViewportH = clampNonNegative(contentRect.h - (showHorizontal ? 1 : 0));
+        const nextVertical = meta.contentHeight > nextViewportH;
+        const nextHorizontal = meta.contentWidth > nextViewportW;
+        if (nextVertical === showVertical && nextHorizontal === showHorizontal) {
+            break;
+        }
+        showVertical = nextVertical;
+        showHorizontal = nextHorizontal;
     }
-    return createShadowConfig({
-        color: theme.colors.border,
-        offsetX,
-        offsetY,
-        ...(density !== undefined ? { density } : {}),
-    });
+    const viewportW = clampNonNegative(contentRect.w - (showVertical ? 1 : 0));
+    const viewportH = clampNonNegative(contentRect.h - (showHorizontal ? 1 : 0));
+    const maxScrollX = Math.max(0, meta.contentWidth - viewportW);
+    const maxScrollY = Math.max(0, meta.contentHeight - viewportH);
+    return {
+        viewportRect: {
+            x: contentRect.x,
+            y: contentRect.y,
+            w: viewportW,
+            h: viewportH,
+        },
+        showVertical,
+        showHorizontal,
+        scrollX: Math.min(meta.scrollX, maxScrollX),
+        scrollY: Math.min(meta.scrollY, maxScrollY),
+        contentWidth: meta.contentWidth,
+        contentHeight: meta.contentHeight,
+    };
 }
-export function renderContainerWidget(builder, rect, currentClip, viewport, theme, parentStyle, node, layoutNode, nodeStack, styleStack, layoutStack, clipStack, damageRect) {
+function drawScrollbars(builder, viewport, style, theme, scrollbarVariant, scrollbarOwnStyle) {
+    const trackFg = theme.colors["border.subtle"] ?? theme.colors.border;
+    const thumbFg = theme.colors["border.strong"] ?? theme.colors.border;
+    const trackStyle = scrollbarOwnStyle
+        ? mergeTextStyle(mergeTextStyle(style, { fg: trackFg }), scrollbarOwnStyle)
+        : mergeTextStyle(style, { fg: trackFg });
+    const thumbStyle = scrollbarOwnStyle
+        ? mergeTextStyle(mergeTextStyle(style, { fg: thumbFg }), scrollbarOwnStyle)
+        : mergeTextStyle(style, { fg: thumbFg });
+    const variantConfig = scrollbarVariant === "minimal"
+        ? SCROLLBAR_RENDER_CONFIG
+        : (SCROLLBAR_CONFIGS[scrollbarVariant] ?? SCROLLBAR_RENDER_CONFIG);
+    const thumbGlyph = variantConfig.glyphs?.thumb;
+    if (viewport.showVertical && viewport.viewportRect.h > 0) {
+        const maxScrollY = Math.max(0, viewport.contentHeight - viewport.viewportRect.h);
+        const position = maxScrollY > 0 ? viewport.scrollY / maxScrollY : 0;
+        const viewportRatio = viewport.contentHeight > 0
+            ? Math.min(1, viewport.viewportRect.h / viewport.contentHeight)
+            : 1;
+        const glyphs = renderVerticalScrollbar(viewport.viewportRect.h, { position, viewportRatio }, variantConfig);
+        const x = viewport.viewportRect.x + viewport.viewportRect.w;
+        for (let dy = 0; dy < glyphs.length; dy++) {
+            const glyph = glyphs[dy];
+            if (!glyph)
+                continue;
+            builder.drawText(x, viewport.viewportRect.y + dy, glyph, glyph === thumbGlyph ? thumbStyle : trackStyle);
+        }
+    }
+    if (viewport.showHorizontal && viewport.viewportRect.w > 0) {
+        const maxScrollX = Math.max(0, viewport.contentWidth - viewport.viewportRect.w);
+        const position = maxScrollX > 0 ? viewport.scrollX / maxScrollX : 0;
+        const viewportRatio = viewport.contentWidth > 0 ? Math.min(1, viewport.viewportRect.w / viewport.contentWidth) : 1;
+        const glyphs = renderHorizontalScrollbar(viewport.viewportRect.w, { position, viewportRatio }, variantConfig);
+        const y = viewport.viewportRect.y + viewport.viewportRect.h;
+        for (let dx = 0; dx < glyphs.length; dx++) {
+            const glyph = glyphs[dx];
+            if (!glyph)
+                continue;
+            builder.drawText(viewport.viewportRect.x + dx, y, glyph, glyph === thumbGlyph ? thumbStyle : trackStyle);
+        }
+    }
+    if (viewport.showVertical && viewport.showHorizontal) {
+        const x = viewport.viewportRect.x + viewport.viewportRect.w;
+        const y = viewport.viewportRect.y + viewport.viewportRect.h;
+        const corner = variantConfig.glyphs?.track ?? " ";
+        builder.drawText(x, y, corner, trackStyle);
+    }
+}
+export function renderContainerWidget(builder, rect, currentClip, viewport, theme, parentStyle, node, layoutNode, nodeStack, styleStack, layoutStack, clipStack, damageRect, skipCleanSubtrees, forceSubtreeRender, boxOpacityOverride) {
     const vnode = node.vnode;
+    const forceChildrenRender = forceSubtreeRender || node.selfDirty;
     switch (vnode.kind) {
+        case "fragment": {
+            const childClip = currentClip;
+            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect, skipCleanSubtrees, forceChildrenRender, undefined, clipOnFirstQueuedChild(builder, nodeStack, currentClip, childClip));
+            break;
+        }
         case "row":
-        case "column": {
+        case "column":
+        case "grid": {
             if (!isVisibleRect(rect))
                 break;
             const props = vnode.props;
-            const ownStyle = asTextStyle(props.style);
-            const style = ownStyle ? mergeTextStyle(parentStyle, ownStyle) : parentStyle;
+            const ownStyle = asTextStyle(props.style, theme);
+            const inheritedStyle = asTextStyle(props.inheritStyle, theme);
+            const baseStyle = inheritedStyle ? mergeTextStyle(parentStyle, inheritedStyle) : parentStyle;
+            const style = ownStyle ? mergeTextStyle(baseStyle, ownStyle) : baseStyle;
             if (ownStyle && shouldFillForStyleOverride(ownStyle)) {
                 builder.fillRect(rect.x, rect.y, rect.w, rect.h, style);
             }
             const spacing = resolveSpacingFromProps(props);
-            // Fast path: no spacing → childClip equals rect, avoid allocation.
-            if (spacing.top === 0 && spacing.right === 0 && spacing.bottom === 0 && spacing.left === 0) {
-                if (!clipEquals(currentClip, rect)) {
-                    builder.pushClip(rect.x, rect.y, rect.w, rect.h);
-                    nodeStack.push(null);
-                }
-                pushChildrenWithLayout(node, layoutNode, style, nodeStack, styleStack, layoutStack, clipStack, rect, damageRect, vnode.kind);
-                break;
-            }
             const cx = rect.x + spacing.left;
             const cy = rect.y + spacing.top;
             const cw = clampNonNegative(rect.w - spacing.left - spacing.right);
             const ch = clampNonNegative(rect.h - spacing.top - spacing.bottom);
-            const childClip = { x: cx, y: cy, w: cw, h: ch };
-            if (!clipEquals(currentClip, childClip)) {
-                builder.pushClip(cx, cy, cw, ch);
-                nodeStack.push(null);
+            const contentRect = { x: cx, y: cy, w: cw, h: ch };
+            const overflowMode = readOverflowMode(props.overflow);
+            let childClip = overflowMode === "visible" ? currentClip : contentRect;
+            if (overflowMode === "scroll") {
+                const meta = readOverflowMetadata(layoutNode, contentRect);
+                const viewportWithScrollbars = resolveScrollViewport(contentRect, meta);
+                const scrollbarVariant = readScrollbarVariant(props.scrollbarVariant);
+                const scrollbarOwnStyle = asTextStyle(props.scrollbarStyle, theme);
+                drawScrollbars(builder, viewportWithScrollbars, style, theme, scrollbarVariant, scrollbarOwnStyle);
+                childClip = viewportWithScrollbars.viewportRect;
             }
-            pushChildrenWithLayout(node, layoutNode, style, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect, vnode.kind);
+            pushChildrenWithLayout(node, layoutNode, style, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect, skipCleanSubtrees, forceChildrenRender, vnode.kind === "row" || vnode.kind === "column" ? vnode.kind : undefined, clipOnFirstQueuedChild(builder, nodeStack, currentClip, childClip));
             break;
         }
         case "box": {
@@ -150,7 +423,17 @@ export function renderContainerWidget(builder, rect, currentClip, viewport, them
                 break;
             const props = vnode.props;
             const spacing = resolveSpacingFromProps(props);
-            const border = readBoxBorder(props.border);
+            const colorTokens = getColorTokens(theme);
+            const surfacePresetConfig = resolveSurfacePresetConfig(props.preset);
+            const surfaceDefaults = colorTokens !== null && surfacePresetConfig !== undefined
+                ? surfaceRecipe(colorTokens, {
+                    elevation: surfacePresetConfig.elevation,
+                    cardLike: surfacePresetConfig.cardLike,
+                })
+                : null;
+            const border = props.border === undefined
+                ? readBoxBorder(surfaceDefaults?.border)
+                : readBoxBorder(props.border);
             const defaultSide = border !== "none";
             const borderTop = typeof props.borderTop === "boolean" ? props.borderTop : defaultSide;
             const borderRight = typeof props.borderRight === "boolean" ? props.borderRight : defaultSide;
@@ -158,21 +441,62 @@ export function renderContainerWidget(builder, rect, currentClip, viewport, them
             const borderLeft = typeof props.borderLeft === "boolean" ? props.borderLeft : defaultSide;
             const title = typeof props.title === "string" ? props.title : undefined;
             const titleAlign = readTitleAlign(props.titleAlign);
-            const ownStyle = asTextStyle(props.style);
-            const style = mergeTextStyle(parentStyle, ownStyle);
-            const shadowConfig = resolveBoxShadowConfig(props.shadow, theme);
+            const ownStyle = asTextStyle(props.style, theme);
+            const borderOwnStyle = asTextStyle(props.borderStyle ?? surfaceDefaults?.borderStyle, theme);
+            const borderSideOwnStyles = mergeBorderSideStyles(surfaceDefaults?.borderStyleSides, readBorderSideStyleMap(props.borderStyleSides, theme));
+            const inheritedStyle = asTextStyle(props.inheritStyle, theme);
+            const baseStyle = inheritedStyle ? mergeTextStyle(parentStyle, inheritedStyle) : parentStyle;
+            const mergedStyle = mergeTextStyle(mergeTextStyle(baseStyle, surfaceDefaults?.bg), ownStyle);
+            // When borderStyle is set, decouple border appearance from child content:
+            // - contentStyle is passed to children (style without borderStyle)
+            // - effectiveBorderStyle is used for border/shadow rendering
+            const hasBorderStyle = borderOwnStyle !== undefined;
+            const contentStyle = mergedStyle;
+            const effectiveBorderStyle = hasBorderStyle
+                ? mergeTextStyle(baseStyle, borderOwnStyle)
+                : mergedStyle;
+            const style = boxOpacityOverride === undefined
+                ? contentStyle
+                : applyOpacityToStyle(contentStyle, boxOpacityOverride, parentStyle.bg);
+            const borderDrawStyle = boxOpacityOverride === undefined
+                ? effectiveBorderStyle
+                : applyOpacityToStyle(effectiveBorderStyle, boxOpacityOverride, parentStyle.bg);
+            const resolveBorderSideDrawStyle = (sideStyle) => {
+                const merged = mergeTextStyle(effectiveBorderStyle, sideStyle);
+                return boxOpacityOverride === undefined
+                    ? merged
+                    : applyOpacityToStyle(merged, boxOpacityOverride, parentStyle.bg);
+            };
+            const borderSideDrawStyle = borderSideOwnStyles
+                ? {
+                    ...(borderSideOwnStyles.top
+                        ? { top: resolveBorderSideDrawStyle(borderSideOwnStyles.top) }
+                        : {}),
+                    ...(borderSideOwnStyles.right
+                        ? { right: resolveBorderSideDrawStyle(borderSideOwnStyles.right) }
+                        : {}),
+                    ...(borderSideOwnStyles.bottom
+                        ? { bottom: resolveBorderSideDrawStyle(borderSideOwnStyles.bottom) }
+                        : {}),
+                    ...(borderSideOwnStyles.left
+                        ? { left: resolveBorderSideDrawStyle(borderSideOwnStyles.left) }
+                        : {}),
+                }
+                : undefined;
+            const shadowConfig = resolveBoxShadowConfig(props.shadow === undefined ? (surfaceDefaults?.shadow ?? false) : props.shadow, theme.colors.border);
             if (shadowConfig) {
-                renderShadow(builder, rect, shadowConfig, style);
+                renderShadow(builder, rect, shadowConfig, borderDrawStyle);
             }
-            if (isVisibleRect(rect) && shouldFillForStyleOverride(ownStyle)) {
+            if (isVisibleRect(rect) &&
+                (shouldFillForStyleOverride(ownStyle) || surfaceDefaults?.bg.bg !== undefined)) {
                 builder.fillRect(rect.x, rect.y, rect.w, rect.h, style);
             }
-            renderBoxBorder(builder, rect, border, title, titleAlign, style, {
+            renderBoxBorder(builder, rect, border, title, titleAlign, borderDrawStyle, {
                 top: borderTop,
                 right: borderRight,
                 bottom: borderBottom,
                 left: borderLeft,
-            });
+            }, borderSideDrawStyle);
             const bt = border === "none" || !borderTop ? 0 : 1;
             const br = border === "none" || !borderRight ? 0 : 1;
             const bb = border === "none" || !borderBottom ? 0 : 1;
@@ -181,12 +505,18 @@ export function renderContainerWidget(builder, rect, currentClip, viewport, them
             const cy = rect.y + bt + spacing.top;
             const cw = clampNonNegative(rect.w - bl - br - spacing.left - spacing.right);
             const ch = clampNonNegative(rect.h - bt - bb - spacing.top - spacing.bottom);
-            const childClip = { x: cx, y: cy, w: cw, h: ch };
-            if (!clipEquals(currentClip, childClip)) {
-                builder.pushClip(cx, cy, cw, ch);
-                nodeStack.push(null);
+            const contentRect = { x: cx, y: cy, w: cw, h: ch };
+            const overflowMode = readOverflowMode(props.overflow);
+            let childClip = overflowMode === "visible" ? currentClip : contentRect;
+            if (overflowMode === "scroll") {
+                const meta = readOverflowMetadata(layoutNode, contentRect);
+                const viewportWithScrollbars = resolveScrollViewport(contentRect, meta);
+                const scrollbarVariant = readScrollbarVariant(props.scrollbarVariant);
+                const scrollbarOwnStyle = asTextStyle(props.scrollbarStyle, theme);
+                drawScrollbars(builder, viewportWithScrollbars, style, theme, scrollbarVariant, scrollbarOwnStyle);
+                childClip = viewportWithScrollbars.viewportRect;
             }
-            pushChildrenWithLayout(node, layoutNode, style, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect);
+            pushChildrenWithLayout(node, layoutNode, style, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect, skipCleanSubtrees, forceChildrenRender, undefined, clipOnFirstQueuedChild(builder, nodeStack, currentClip, childClip));
             break;
         }
         case "modal": {
@@ -194,49 +524,67 @@ export function renderContainerWidget(builder, rect, currentClip, viewport, them
                 break;
             const props = vnode.props;
             const title = typeof props.title === "string" ? props.title : undefined;
-            const backdrop = props.backdrop === "none" ? "none" : props.backdrop === "opaque" ? "opaque" : "dim";
+            const frame = readOverlayFrameColors(props.frameStyle);
+            const surfaceStyle = mergeTextStyle(parentStyle, toOverlaySurfaceStyle(frame));
+            const borderStyle = frame.border !== undefined
+                ? mergeTextStyle(surfaceStyle, { fg: frame.border })
+                : surfaceStyle;
+            const backdrop = resolveModalBackdrop(props.backdrop);
+            const colorTokens = getColorTokens(theme);
+            const modalDefaults = colorTokens !== null ? modalRecipe(colorTokens, { focused: true }) : null;
             const fill = currentClip ?? { x: 0, y: 0, w: viewport.cols, h: viewport.rows };
-            if (backdrop === "opaque") {
-                builder.fillRect(fill.x, fill.y, fill.w, fill.h, { bg: theme.colors.bg });
+            if (backdrop.variant === "opaque") {
+                builder.fillRect(fill.x, fill.y, fill.w, fill.h, {
+                    bg: backdrop.background ?? theme.colors.bg,
+                });
             }
-            else if (backdrop === "dim") {
+            else if (backdrop.variant === "dim") {
                 if (fill.w > 0 && fill.h > 0) {
-                    const line = "░".repeat(fill.w);
-                    const style = { fg: theme.colors.border, bg: theme.colors.bg };
+                    const line = backdrop.pattern.repeat(fill.w);
+                    const style = {
+                        fg: backdrop.foreground ?? theme.colors.border,
+                        bg: backdrop.background ?? theme.colors.bg,
+                        attrs: 0,
+                    };
                     for (let dy = 0; dy < fill.h; dy++) {
                         builder.drawText(fill.x, fill.y + dy, line, style);
                     }
                 }
             }
-            renderBoxBorder(builder, rect, "single", title, "left", parentStyle);
+            const shadowConfig = resolveBoxShadowConfig(modalDefaults?.shadow ?? false, theme.colors.border);
+            if (shadowConfig) {
+                renderShadow(builder, rect, shadowConfig, borderStyle);
+            }
+            if (frame.background !== undefined) {
+                builder.fillRect(rect.x, rect.y, rect.w, rect.h, surfaceStyle);
+            }
+            renderBoxBorder(builder, rect, "single", title, "left", borderStyle);
             // Clip modal interior (exclude border)
             const cx = rect.x + 1;
             const cy = rect.y + 1;
             const cw = clampNonNegative(rect.w - 2);
             const ch = clampNonNegative(rect.h - 2);
             const childClip = { x: cx, y: cy, w: cw, h: ch };
-            if (!clipEquals(currentClip, childClip)) {
-                builder.pushClip(cx, cy, cw, ch);
-                nodeStack.push(null);
-            }
-            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect);
+            pushChildrenWithLayout(node, layoutNode, surfaceStyle, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect, skipCleanSubtrees, forceChildrenRender, undefined, clipOnFirstQueuedChild(builder, nodeStack, currentClip, childClip));
             break;
         }
         case "focusZone":
         case "focusTrap": {
             // Focus zones and traps are transparent - just render children
-            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, currentClip, damageRect);
+            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, currentClip, damageRect, skipCleanSubtrees, forceChildrenRender);
             break;
         }
         case "layers": {
             // Layers container: render children in order (later = on top)
             // Each child is rendered at the same position
-            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, currentClip, damageRect);
+            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, currentClip, damageRect, skipCleanSubtrees, forceChildrenRender);
             break;
         }
         case "layer": {
             // Generic layer: transparent container for its content VNode.
             const props = vnode.props;
+            const frame = readOverlayFrameColors(props.frameStyle);
+            const layerStyle = mergeTextStyle(parentStyle, toOverlaySurfaceStyle(frame));
             const backdrop = props.backdrop === "dim" || props.backdrop === "opaque" || props.backdrop === "none"
                 ? props.backdrop
                 : "none";
@@ -248,14 +596,34 @@ export function renderContainerWidget(builder, rect, currentClip, viewport, them
                 else if (backdrop === "dim") {
                     if (fill.w > 0 && fill.h > 0) {
                         const line = "░".repeat(fill.w);
-                        const style = { fg: theme.colors.border, bg: theme.colors.bg };
+                        const style = {
+                            fg: theme.colors.border,
+                            bg: theme.colors.bg,
+                            attrs: 0,
+                        };
                         for (let dy = 0; dy < fill.h; dy++) {
                             builder.drawText(fill.x, fill.y + dy, line, style);
                         }
                     }
                 }
             }
-            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, currentClip, damageRect);
+            if (frame.background !== undefined) {
+                builder.fillRect(rect.x, rect.y, rect.w, rect.h, layerStyle);
+            }
+            if (frame.border !== undefined) {
+                const borderStyle = mergeTextStyle(layerStyle, { fg: frame.border });
+                renderBoxBorder(builder, rect, "single", undefined, "left", borderStyle);
+            }
+            const borderInset = frame.border !== undefined ? 1 : 0;
+            const childClip = borderInset > 0
+                ? {
+                    x: rect.x + borderInset,
+                    y: rect.y + borderInset,
+                    w: clampNonNegative(rect.w - borderInset * 2),
+                    h: clampNonNegative(rect.h - borderInset * 2),
+                }
+                : currentClip;
+            pushChildrenWithLayout(node, layoutNode, layerStyle, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect, skipCleanSubtrees, forceChildrenRender, undefined, clipOnFirstQueuedChild(builder, nodeStack, currentClip, childClip));
             break;
         }
         case "splitPane": {
@@ -265,12 +633,8 @@ export function renderContainerWidget(builder, rect, currentClip, viewport, them
             const { direction, dividerSize = 1 } = vnode.props;
             const dividerStyle = mergeTextStyle(parentStyle, { fg: theme.colors.border });
             const childClip = { x: rect.x, y: rect.y, w: rect.w, h: rect.h };
-            if (!clipEquals(currentClip, childClip)) {
-                builder.pushClip(rect.x, rect.y, rect.w, rect.h);
-                nodeStack.push(null);
-            }
             // Render children (handled by layout)
-            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect);
+            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect, skipCleanSubtrees, forceChildrenRender, undefined, clipOnFirstQueuedChild(builder, nodeStack, currentClip, childClip));
             // Render dividers between panels
             const childCount = Math.min(node.children.length, layoutNode.children.length);
             if (direction === "horizontal") {
@@ -313,11 +677,7 @@ export function renderContainerWidget(builder, rect, currentClip, viewport, them
             if (!isVisibleRect(rect))
                 break;
             const childClip = { x: rect.x, y: rect.y, w: rect.w, h: rect.h };
-            if (!clipEquals(currentClip, childClip)) {
-                builder.pushClip(rect.x, rect.y, rect.w, rect.h);
-                nodeStack.push(null);
-            }
-            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect);
+            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect, skipCleanSubtrees, forceChildrenRender, undefined, clipOnFirstQueuedChild(builder, nodeStack, currentClip, childClip));
             break;
         }
         case "resizablePanel": {
@@ -325,11 +685,7 @@ export function renderContainerWidget(builder, rect, currentClip, viewport, them
             if (!isVisibleRect(rect))
                 break;
             const childClip = { x: rect.x, y: rect.y, w: rect.w, h: rect.h };
-            if (!clipEquals(currentClip, childClip)) {
-                builder.pushClip(rect.x, rect.y, rect.w, rect.h);
-                nodeStack.push(null);
-            }
-            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect);
+            pushChildrenWithLayout(node, layoutNode, parentStyle, nodeStack, styleStack, layoutStack, clipStack, childClip, damageRect, skipCleanSubtrees, forceChildrenRender, undefined, clipOnFirstQueuedChild(builder, nodeStack, currentClip, childClip));
             break;
         }
         default: