silvery 0.18.2 → 0.19.1

package/dist/{render-string-DVfgc8xr.mjs → render-string-X-CxpTdZ.mjs}

@@ -1,13 +1,16 @@
-import { c as signal, i as syncRectSignals, o as computed, t as rectEqual } from "./types-e4dpfbSa.mjs";
-import { c as TermContext, o as StderrContext, s as StdoutContext } from "./context-BjWgrikx.mjs";
-import { At as bufferToText, Dt as TerminalBuffer, Et as DEFAULT_BG, Ft as createTextFrame, H as ensureEmojiPresentation, I as canBreakAnywhere, It as init_buffer, K as graphemeWidth, Lt as isDefaultBg, Ot as ansi256ToRgb, Pt as createMutableCell, U as getActiveLineHeight, V as displayWidthAnsi, _t as wrapText, a as hostConfig, at as parseAnsiText, b as createTerm, c as clearDirtyTracking, d as collectPlainText, et as isWordBoundary, f as advanceRenderEpoch, ft as splitGraphemes, g as isDirty, h as isCurrentEpoch, kt as bufferToStyledText, l as hasScrollDirty, lt as sliceByWidth, m as isAnyDirty, ot as runWithMeasurer, p as getRenderEpoch, pt as splitGraphemesAnsiAware, q as hasAnsi, r as getContainerRoot, t as createContainer, u as measureStats, ut as sliceByWidthFromEnd } from "./reconciler-B8uxQxaU.mjs";
-import { T as resolveThemeColor, k as blend, t as init_src, x as monoAttrsForColorString } from "./src-D_BS-as7.mjs";
-import { A as pushContextTheme, D as getActiveTheme, E as getActiveColorLevel, O as init_state, k as popContextTheme, t as init_src$1, x as init_resolve } from "./src-C0sOQW-t.mjs";
-import { i as isLayoutEngineInitialized, r as getLayoutEngine } from "./layout-engine-Dr3cY5U4.mjs";
+import { c as signal, i as syncRectSignals, o as computed, t as rectEqual } from "./types-Bk2yw9Qj.mjs";
+import { c as StdoutContext, l as TermContext, s as StderrContext } from "./context-BU5LkkIy.mjs";
+import { At as bufferToText, Dt as TerminalBuffer, Et as DEFAULT_BG, Ft as createTextFrame, H as ensureEmojiPresentation, I as canBreakAnywhere, It as init_buffer, K as graphemeWidth, Lt as isDefaultBg, Ot as ansi256ToRgb, Pt as createMutableCell, U as getActiveLineHeight, V as displayWidthAnsi, Z as isLikelyEmoji, _t as wrapText, a as hostConfig, at as parseAnsiText, b as createTerm, c as clearDirtyTracking, d as collectPlainText, et as isWordBoundary, f as advanceRenderEpoch, ft as splitGraphemes, g as isDirty, h as isCurrentEpoch, kt as bufferToStyledText, l as hasScrollDirty, lt as sliceByWidth, m as isAnyDirty, ot as runWithMeasurer, p as getRenderEpoch, pt as splitGraphemesAnsiAware, q as hasAnsi, r as getContainerRoot, t as createContainer, u as measureStats, ut as sliceByWidthFromEnd } from "./reconciler-Cwgm8hRR.mjs";
+import { A as backdropPlacementId, F as kittyUploadScrimImage, M as cupTo, N as kittyDeleteAllScrimPlacements, P as kittyPlaceAt, j as buildScrimPixels, k as resolveThemeColor, t as init_src, w as monoAttrsForColorString } from "./src-NCKb8kE5.mjs";
+import { i as isLayoutEngineInitialized, r as getLayoutEngine } from "./layout-engine-ClUgv6jB.mjs";
+import { x as ansi16DarkTheme } from "./src-B5GjfG7g.mjs";
 import React, { act } from "react";
 import { createLogger } from "loggily";
+import * as Upstream from "@silvery/color";
+import { relativeLuminance } from "@silvery/color";
 import Reconciler from "react-reconciler";
 //#region packages/ag-term/src/pipeline/prepared-text.ts
+init_buffer();
 const MAX_FORMAT_ENTRIES = 4;
 /** Content-affecting flags that invalidate plain text. */
 const PLAIN_TEXT_DIRTY = 9;
@@ -29,6 +32,7 @@ function getOrCreate(node) {
 			plainTextLineCount: 0,
 			collected: null,
 			collectedMaxDisplayWidth: void 0,
+			collectedContextTheme: null,
 			formats: [],
 			analysis: null
 		};
@@ -61,9 +65,15 @@ function setCachedPlainText(node, text, lineCount) {
 }
 /**
 * Get cached collected text (from collectTextWithBg).
-* Invalidated by content, children, style, or bg changes, or maxDisplayWidth mismatch.
+* Invalidated by content, children, style, or bg changes, maxDisplayWidth mismatch,
+* or a context theme change (ancestor ThemeProvider changed token values).
+*
+* @param contextTheme - The active theme at the time of rendering (from getActiveTheme()).
+*   Used as a cache key so that when the nearest-ancestor ThemeProvider changes its
+*   merged theme, text nodes that embed $token ANSI codes in their collected text
+*   are re-collected with the new token values. Pass null when no theme context exists.
 */
-function getCachedCollectedText(node, maxDisplayWidth) {
+function getCachedCollectedText(node, maxDisplayWidth, contextTheme) {
 	if (_cacheDisabled) return null;
 	const entry = textCaches.get(node);
 	if (!entry?.collected) return null;
@@ -79,13 +89,20 @@ function getCachedCollectedText(node, maxDisplayWidth) {
 		entry.analysis = null;
 		return null;
 	}
+	if (entry.collectedContextTheme !== contextTheme) {
+		entry.collected = null;
+		entry.formats = [];
+		entry.analysis = null;
+		return null;
+	}
 	return entry.collected;
 }
 /** Store collected text in cache. */
-function setCachedCollectedText(node, result, maxDisplayWidth) {
+function setCachedCollectedText(node, result, maxDisplayWidth, contextTheme) {
 	const entry = getOrCreate(node);
 	entry.collected = result;
 	entry.collectedMaxDisplayWidth = maxDisplayWidth;
+	entry.collectedContextTheme = contextTheme;
 }
 /**
 * Get cached formatted lines for the given width/wrap/trim.
@@ -851,6 +868,44 @@ function scrollPhase(root, options = {}) {
 	});
 }
 /**
+* Snap scroll offset so the first visible child (after the top overflow
+* indicator's reserved row) aligns with a child-top boundary.
+*
+* When scrolling "down to show the target at the bottom," the raw offset
+* `target.bottom - effectiveHeight` assumes the entire viewport above the
+* bottom-indicator is usable content. But the TOP overflow indicator also
+* consumes a row when `hiddenAbove > 0`, rendering at viewport row 0 on top
+* of whatever child starts there. If that row is a card's top border, the
+* border is overwritten — users see a "headless" card and perceive the
+* column as "gotten shorter" (see km-tui `column-top-disappears`).
+*
+* This snap shifts the offset so `offset + 1 === firstFullyVisibleChild.top`:
+* the top-indicator row coincides with the 1-row gap ABOVE the first child,
+* not with that child's content. When children have heterogeneous heights,
+* this means moving the viewport DOWN by a few rows (so an earlier, shorter
+* child scrolls fully off-screen and the next child starts cleanly).
+*
+* Guardrails:
+* - Never snap past the target's own top (keeps the target visible).
+* - If no suitable boundary exists above `rawOffset + 1` and ≤ `target.top`,
+*   returns `rawOffset` unchanged (scroll behaves as before).
+* - Returns 0 unchanged — offset=0 means no top indicator, no conflict.
+*/
+function snapOffsetToChildTop(rawOffset, childPositions, target) {
+	if (rawOffset <= 0) return rawOffset;
+	let bestChildTop = -1;
+	for (const cp of childPositions) {
+		if (cp.isSticky) continue;
+		if (cp.top === cp.bottom) continue;
+		if (cp.top > rawOffset && cp.top <= target.top) {
+			if (bestChildTop === -1 || cp.top < bestChildTop) bestChildTop = cp.top;
+		}
+	}
+	if (bestChildTop === -1) return rawOffset;
+	const snapped = bestChildTop - 1;
+	return snapped >= rawOffset ? snapped : rawOffset;
+}
+/**
 * Calculate scroll state for a single scrollable container.
 */
 function calculateScrollState(node, props, skipStateUpdates) {
@@ -894,8 +949,8 @@ function calculateScrollState(node, props, skipStateUpdates) {
 			const effectiveHeight = viewportHeight - indicatorReserve;
 			const visibleTop = scrollOffset;
 			const visibleBottom = scrollOffset + effectiveHeight;
-			if (target.top < visibleTop) scrollOffset = target.top;
-			else if (target.bottom > visibleBottom) scrollOffset = target.bottom - effectiveHeight;
+			if (target.top < visibleTop) scrollOffset = target.top > 0 ? target.top - 1 : 0;
+			else if (target.bottom > visibleBottom) scrollOffset = snapOffsetToChildTop(target.bottom - effectiveHeight, childPositions, target);
 		}
 	}
 	scrollOffset = Math.max(0, scrollOffset);
@@ -1209,10 +1264,66 @@ function detectPipelineFeatures(root) {
 	};
 }
 //#endregion
+//#region packages/ag-term/src/pipeline/state.ts
+/**
+* Safe fallback theme. Never mutated — the theme flows via the AgNode tree
+* (Box theme= prop + pushContextTheme/popContextTheme in render-phase.ts).
+* This is only returned by getActiveTheme() when called from a code path that
+* has no pushContextTheme frame on the stack, e.g. a bare test that renders
+* without ThemeProvider.
+*
+* `@silvery/theme`'s `ansi16DarkTheme` ships with Sterling flat tokens baked
+* in, so bare-test render paths resolve `$fg-accent` / `$bg-surface-subtle` /
+* etc. without needing an explicit ThemeProvider.
+*/
+const _activeTheme = ansi16DarkTheme;
+/** Get the active theme (fallback to ansi16DarkTheme when no context stack entry exists). */
+function getActiveTheme() {
+	return _contextStack.length > 0 ? _contextStack[_contextStack.length - 1] : _activeTheme;
+}
+let _activeColorLevel = "truecolor";
+/** Set the active color level (called by the runtime based on TerminalCaps). */
+function setActiveColorLevel(level) {
+	_activeColorLevel = level;
+}
+/** Get the active color level (called by parseColor / getTextStyle in render-helpers). */
+function getActiveColorLevel() {
+	return _activeColorLevel;
+}
+/**
+* Stack of per-subtree theme overrides, pushed/popped during render phase
+* tree walk. When a Box has a `theme` prop, its theme is pushed before
+* rendering children and popped after. getActiveTheme() checks this stack
+* first, falling back to _activeTheme.
+*
+* This enables CSS custom property-like cascading: the nearest ancestor
+* Box with a theme prop determines $token resolution for its subtree.
+* ThemeProvider (in @silvery/ag-react) renders a <Box theme={merged}>
+* wrapper, so its theme is naturally pushed via this mechanism.
+*/
+const _contextStack = [];
+/** Push a context theme (called by render phase for Box nodes with theme prop). */
+function pushContextTheme(theme) {
+	_contextStack.push(theme);
+}
+/** Pop a context theme (called by render phase after processing Box subtree). */
+function popContextTheme() {
+	_contextStack.pop();
+}
+//#endregion
 //#region packages/ag-term/src/pipeline/render-helpers.ts
-init_buffer();
-init_state();
-init_resolve();
+/**
+* Render Helpers - Pure utility functions for content rendering.
+*
+* Contains:
+* - Color parsing (parseColor)
+* - Border character definitions (getBorderChars)
+* - Style extraction (getTextStyle)
+* - Text width utilities (getTextWidth)
+*
+* Re-exports layout helpers from helpers.ts:
+* - getPadding, getBorderSize
+*/
 init_src();
 const namedColors = {
 	black: 0,
@@ -2142,7 +2253,8 @@ function renderText(node, buffer, layout, props, nodeState, inheritedBg, inherit
 		inverse: props.inverse,
 		strikethrough: props.strikethrough
 	};
-	const cachedCollected = getCachedCollectedText(node, maxDisplayWidth);
+	const contextTheme = getActiveTheme();
+	const cachedCollected = getCachedCollectedText(node, maxDisplayWidth, contextTheme);
 	if (cachedCollected) {
 		text = cachedCollected.text;
 		bgSegments = cachedCollected.bgSegments;
@@ -2152,7 +2264,7 @@ function renderText(node, buffer, layout, props, nodeState, inheritedBg, inherit
 		text = collected.text;
 		bgSegments = collected.bgSegments;
 		childSpans = collected.childSpans;
-		setCachedCollectedText(node, collected, maxDisplayWidth);
+		setCachedCollectedText(node, collected, maxDisplayWidth, contextTheme);
 	}
 	const style = getTextStyle(props);
 	if (style.fg === null && inheritedFg !== void 0) style.fg = inheritedFg;
@@ -2247,12 +2359,20 @@ function computeInlineRects(childSpans, lineOffsets, parentX, parentY, lineCount
 //#region packages/ag-term/src/pipeline/render-box.ts
 /**
 * Get the effective background color string for a Box.
-* Returns explicit backgroundColor if set, otherwise theme.bg if theme is set.
+* Returns explicit `backgroundColor` if set, otherwise the Theme's root
+* surface background — Sterling's `bg-surface-default` if present, falling
+* back to the legacy `bg` root for any pre-Sterling Theme shape.
 * Used by both renderBox (paint fill) and render-phase (cascade logic).
 */
 function getEffectiveBg(props) {
 	if (props.backgroundColor) return props.backgroundColor;
-	if (props.theme) return props.theme.bg;
+	if (props.theme) {
+		const theme = props.theme;
+		const sterlingBg = theme["bg-surface-default"];
+		if (typeof sterlingBg === "string") return sterlingBg;
+		const legacyBg = theme["bg"];
+		if (typeof legacyBg === "string") return legacyBg;
+	}
 }
 /**
 * Render a Box node.
@@ -2575,7 +2695,8 @@ function walk(node, buffer, scrollOffset, clipBounds, inheritedBg, snapshots) {
 	if (y >= buffer.height || y + layout.height <= 0) return;
 	const effectiveBg = getEffectiveBg(props);
 	const theme = props.theme;
-	const childInheritedBg = effectiveBg ? { color: parseColor(effectiveBg) } : theme ? { color: parseColor(theme.bg) } : inheritedBg;
+	const themeBg = theme && typeof theme["bg-surface-default"] === "string" ? theme["bg-surface-default"] : theme && typeof theme["bg"] === "string" ? theme["bg"] : void 0;
+	const childInheritedBg = effectiveBg ? { color: parseColor(effectiveBg) } : themeBg !== void 0 ? { color: parseColor(themeBg) } : inheritedBg;
 	if (node.type === "silvery-box" && props.outlineStyle) {
 		const boxInheritedBg = effectiveBg ? void 0 : inheritedBg.color;
 		const positions = collectOutlineCells(layout.x, y, layout.width, layout.height, props, clipBounds, buffer);
@@ -2920,7 +3041,6 @@ function getReactiveState(node) {
 *   Region clearing: clearNodeRegion, clearExcessArea, clippedFill
 */
 init_buffer();
-init_state();
 const contentLog = createLogger("silvery:content");
 const traceLog = createLogger("silvery:content:trace");
 const cellLog = createLogger("silvery:content:cell");
@@ -3459,12 +3579,17 @@ function renderScrollContainerChildren(node, buffer, props, nodeState, contentRe
 		right: 0
 	};
 	const padding = getPadding(props);
-	const childClipBounds = computeChildClipBounds(layout, props, clipBounds, 0, false, true);
+	const viewportClipBounds = computeChildClipBounds(layout, props, clipBounds, 0, false, true);
+	const childClipBounds = props.overflowIndicator === true && !props.borderStyle && (ss.hiddenAbove > 0 || ss.hiddenBelow > 0) ? {
+		...viewportClipBounds,
+		top: ss.hiddenAbove > 0 ? viewportClipBounds.top + 1 : viewportClipBounds.top,
+		bottom: ss.hiddenBelow > 0 ? viewportClipBounds.bottom - 1 : viewportClipBounds.bottom
+	} : viewportClipBounds;
 	const scrollOffsetChanged = ss.offset !== ss.prevOffset;
 	const hasStickyChildren = !!(ss.stickyChildren && ss.stickyChildren.length > 0);
 	const visibleRangeChanged = ss.firstVisibleChild !== ss.prevFirstVisibleChild || ss.lastVisibleChild !== ss.prevLastVisibleChild;
-	const clearY = childClipBounds.top;
-	const clearHeight = childClipBounds.bottom - childClipBounds.top;
+	const clearY = viewportClipBounds.top;
+	const clearHeight = viewportClipBounds.bottom - viewportClipBounds.top;
 	const contentX = layout.x + border.left + padding.left;
 	const contentWidth = layout.width - border.left - border.right - padding.left - padding.right;
 	const scrollBg = scrollOffsetChanged || isDirty(node.dirtyBits, node.dirtyEpoch, 8) || childrenNeedFreshRender || visibleRangeChanged ? getEffectiveBg(props) ? parseColor(getEffectiveBg(props)) : inheritedBg.color : null;
@@ -4020,17 +4145,163 @@ function clippedFill(buffer, x, width, top, bottom, clipBounds, outerBottom, bg)
 	});
 }
 //#endregion
-//#region packages/ag-term/src/pipeline/backdrop-phase.ts
-init_src$1();
+//#region packages/ag-term/src/pipeline/backdrop/color.ts
 init_buffer();
-const FADE_ATTR = "data-backdrop-fade";
-const FADE_EXCLUDE_ATTR = "data-backdrop-fade-excluded";
+/** Convert a buffer Color to a `#rrggbb` hex string, or null if unresolvable. */
+function colorToHex(color) {
+	if (color === null) return null;
+	if (typeof color === "number") {
+		const rgb = ansi256ToRgb(color);
+		return rgbToHex(rgb.r, rgb.g, rgb.b);
+	}
+	if (isDefaultBg(color)) return null;
+	return rgbToHex(color.r, color.g, color.b);
+}
+function rgbToHex(r, g, b) {
+	const clamp = (n) => {
+		return Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, "0");
+	};
+	return `#${clamp(r)}${clamp(g)}${clamp(b)}`;
+}
 /**
-* Apply backdrop-fade to the buffer based on tree markers.
+* Parse `#rrggbb` or `#rgb` (any case, with or without leading `#`) into
+* `{ r, g, b }`. Returns null when the input is not a hex color.
 *
-* Returns `true` if at least one region was modified; `false` if nothing
-* changed (no markers found, or colorLevel is `none`).
+* Strict character-class validation — `parseInt("0g", 16)` returns `0`
+* silently, which would accept malformed hex values. Regex guard rejects
+* anything outside `[0-9a-f]` regardless of case.
 */
+function hexToRgb$1(hex) {
+	if (typeof hex !== "string") return null;
+	let s = hex.trim().toLowerCase();
+	if (s.startsWith("#")) s = s.slice(1);
+	if (s.length === 3) {
+		if (!/^[0-9a-f]{3}$/.test(s)) return null;
+		s = s[0] + s[0] + s[1] + s[1] + s[2] + s[2];
+	} else if (!/^[0-9a-f]{6}$/.test(s)) return null;
+	return {
+		r: parseInt(s.slice(0, 2), 16),
+		g: parseInt(s.slice(2, 4), 16),
+		b: parseInt(s.slice(4, 6), 16)
+	};
+}
+/**
+* Normalize any permissible hex input to a canonical `#rrggbb` lowercase
+* string. Handles `#abc` → `#aabbcc` expansion, case folding, optional
+* leading `#`, and surrounding whitespace. Returns null when the input is
+* not a hex color.
+*
+* Applied by `buildPlan` to every user-provided color option
+* (`defaultBg`, `defaultFg`, `scrimColor`) exactly once so downstream
+* comparisons (`scrim === defaultBg`, etc.) work regardless of input
+* casing or shorthand.
+*/
+function normalizeHex(hex) {
+	if (hex === null || hex === void 0) return null;
+	const rgb = hexToRgb$1(hex);
+	if (!rgb) return null;
+	return rgbToHex(rgb.r, rgb.g, rgb.b);
+}
+//#endregion
+//#region packages/ag-term/src/pipeline/backdrop/plan.ts
+/**
+* Backdrop fade — stage 1: build the immutable `Plan`.
+*
+* `buildPlan(root, options)` is a PURE, capability-independent pass that
+* walks the tree, collects `data-backdrop-fade` / `data-backdrop-fade-excluded`
+* markers, enforces the single-amount invariant, and resolves the scrim +
+* default colors. The realizers (`./realize-buffer.ts`, `./realize-kitty.ts`)
+* trust the plan: they do NOT re-walk the tree, re-resolve the scrim, or
+* re-validate amounts. This module is the single source of truth.
+*
+* ## The model: per-channel alpha scrim with perceptually-aware fg
+*
+* The pass fades every covered cell by blending BOTH fg AND bg toward a
+* neutral scrim color at the caller's `amount`. Default scrim: pure black
+* for dark themes (Apple `colorWithWhite:0.0 alpha:0.4`), pure white for
+* light. Default amount: `DEFAULT_AMOUNT` (0.25) — calibrated against
+* macOS 0.20, Material 3 0.32, iOS 0.40, Flutter 0.54.
+*
+* ### Two operations, one per channel
+*
+*   fg' = deemphasizeOklchToward(fg, amount, towardLight)
+*                                             // OKLCH: L toward 0 or 1,
+*                                             //        C *= (1-α)²
+*   bg' = mixSrgb(bg, scrim, amount)          // sRGB source-over alpha
+*
+* Fg uses OKLCH deemphasize with explicit polarity so colored text
+* deemphasizes toward the correct theme neutral — toward black on dark
+* themes (same formula we've always used), toward white on light themes
+* (new — see `./color-compat.ts` for the math). The quadratic chroma
+* falloff compensates for the human-vision nonlinearity that reads chroma
+* relative to luminance. Bg uses sRGB source-over because the Kitty
+* graphics scrim overlay composites in sRGB at alpha at the hardware
+* level.
+*
+* ### Uniform amount per channel, heaviness tuned at call site
+*
+* Both fg and bg use the same `amount`. An earlier revision halved bg
+* amount to prevent "scene drowning" — that caused border/panel brightness
+* inversion (fg-dominated border darkens faster than bg-dominated fill).
+* Heaviness is controlled by `amount`, not by asymmetric math.
+*
+* ## Scrim color
+*
+* - Dark themes: pure black (`#000000`) — Apple's modal-sheet dimming color.
+* - Light themes: pure white (`#ffffff`) — the sign-flipped equivalent.
+*
+* Null-bg cells are resolved to `defaultBg` first, then `mixSrgb` toward
+* the scrim — empty cells darken at the same rate as explicitly-colored ones.
+*
+* Tiers (`colorLevel`): a single code path for all supported tiers. For
+* `"none"` (monochrome) the pass short-circuits to a no-op. For `basic`,
+* `256`, and `truecolor`, the per-cell operation is identical — the output
+* phase quantizes the mixed truecolor hex to the tier's palette on emit.
+*
+* ## Purity
+*
+* This module is pure: no console I/O, no buffer access, no mutable module
+* state. `buildPlan` returns a `Plan` whose `mixedAmounts` flag signals
+* multi-amount frames; the orchestrator (`./index.ts`) emits the dev-mode
+* warning so stage 1 remains a pure function of its inputs.
+*/
+/** Marker prop key for include rects (fade cells INSIDE the node's rect). */
+const BACKDROP_FADE_ATTR = "data-backdrop-fade";
+/** Marker prop key for exclude rects (fade everything OUTSIDE the node's rect). */
+const BACKDROP_FADE_EXCLUDE_ATTR = "data-backdrop-fade-excluded";
+/**
+* Luminance threshold for dark/light theme detection.
+*
+* 0.18 is well below the WCAG midpoint. Standard dark terminal themes
+* (Catppuccin Mocha bg #1e1e2e, luminance ≈ 0.012; Tokyo Night bg #1a1b26,
+* ≈ 0.010) are well below. Light themes (GitHub Light #ffffff = 1.0) above.
+*/
+const DARK_LUMINANCE_THRESHOLD = .18;
+/** Canonical scrim colors — Apple's `colorWithWhite:0.0` / `:1.0`. */
+const DARK_SCRIM = "#000000";
+const LIGHT_SCRIM = "#ffffff";
+/**
+* Default fade amount — the calibrated baseline used when a marker
+* materializes as a presence attribute (`<Backdrop fade />`,
+* `data-backdrop-fade=""`, `data-backdrop-fade={true}`) without an explicit
+* numeric value. Calibrated against macOS 0.20, Material 3 0.32, iOS 0.40,
+* Flutter 0.54. Re-exported from `index.ts` so downstream callers can
+* reference the same constant.
+*/
+const DEFAULT_AMOUNT = .25;
+/** Sentinel "nothing to do" plan — reused across frames to avoid allocations. */
+const INACTIVE_PLAN = Object.freeze({
+	active: false,
+	amount: 0,
+	scrim: null,
+	defaultBg: null,
+	defaultFg: null,
+	includes: Object.freeze([]),
+	excludes: Object.freeze([]),
+	mixedAmounts: false,
+	scrimTowardLight: false,
+	kittyEnabled: false
+});
 /**
 * Quick check: does the tree contain any backdrop markers? Used as a gate so
 * we don't clone the buffer every frame when no fade is active. Walks the
@@ -4039,106 +4310,432 @@ const FADE_EXCLUDE_ATTR = "data-backdrop-fade-excluded";
 */
 function hasBackdropMarkers(root) {
 	const props = root.props;
-	if (props[FADE_ATTR] !== void 0 || props[FADE_EXCLUDE_ATTR] !== void 0) return true;
+	if (props["data-backdrop-fade"] !== void 0 || props["data-backdrop-fade-excluded"] !== void 0) return true;
 	for (const child of root.children) if (hasBackdropMarkers(child)) return true;
 	return false;
 }
-function applyBackdropFade(root, buffer, options) {
-	const colorLevel = options?.colorLevel ?? "truecolor";
-	if (colorLevel === "none") return false;
+/**
+* Stage 1 — build the immutable `Plan`.
+*
+* Pure function of `(tree markers, options)`. No buffer access, no Kitty
+* capability knowledge, no console I/O. The realizers read from the plan
+* exclusively; the orchestrator (`./index.ts`) handles dev-mode diagnostics
+* derived from `plan.mixedAmounts`.
+*
+* Returns `INACTIVE_PLAN` when:
+* - `colorLevel === "none"` (monochrome terminal — pass is a no-op).
+* - The tree has no backdrop markers, OR all markers have `amount <= 0`.
+*/
+function buildPlan(root, options) {
+	if ((options?.colorLevel ?? "truecolor") === "none") return INACTIVE_PLAN;
 	const includes = [];
 	const excludes = [];
-	collectBackdropMarkers(root, includes, excludes);
-	if (includes.length === 0 && excludes.length === 0) return false;
-	const strategy = colorLevel === "basic" ? "dim" : "blend";
-	let modified = false;
-	for (const { rect, amount } of includes) {
-		if (amount <= 0) continue;
-		if (fadeRect(buffer, rect, amount, strategy)) modified = true;
-	}
-	if (excludes.length > 0) {
-		const fullRect = {
-			x: 0,
-			y: 0,
-			width: buffer.width,
-			height: buffer.height
-		};
-		for (const { rect, amount } of excludes) {
-			if (amount <= 0) continue;
-			if (fadeRectExcluding(buffer, fullRect, rect, amount, strategy)) modified = true;
+	const includeAmounts = [];
+	const excludeAmounts = [];
+	collectBackdropMarkers(root, includes, excludes, includeAmounts, excludeAmounts);
+	if (includes.length === 0 && excludes.length === 0) return INACTIVE_PLAN;
+	const defaultBg = normalizeHex(options?.defaultBg ?? null);
+	const scrimColorOpt = options?.scrimColor;
+	const scrim = (typeof scrimColorOpt === "string" && scrimColorOpt !== "auto" ? normalizeHex(scrimColorOpt) : null) ?? deriveAutoScrimColor(defaultBg);
+	const scrimTowardLight = isLightScrim(scrim);
+	const defaultFg = normalizeHex(options?.defaultFg) ?? (scrim === null ? null : scrimTowardLight ? "#000000" : "#ffffff");
+	const { amount, hasMixedAmounts } = assertSingleAmount(includeAmounts, excludeAmounts);
+	return {
+		active: true,
+		amount,
+		scrim,
+		defaultBg,
+		defaultFg,
+		includes,
+		excludes,
+		mixedAmounts: hasMixedAmounts,
+		scrimTowardLight,
+		kittyEnabled: options?.kittyGraphics === true && scrim !== null
+	};
+}
+/**
+* Detect the single-amount invariant across all markers. Returns the
+* clamped first-observed amount AND a flag indicating whether any later
+* marker differed. The orchestrator uses the flag to emit a dev-mode warn.
+*
+* Mixed amounts currently break the Kitty overlay (one image, one alpha)
+* and have unclear composition semantics (max? source-over compound?).
+* Production behavior is first-wins but will look wrong until the markers
+* are reconciled to a single value.
+*/
+function assertSingleAmount(includeAmounts, excludeAmounts) {
+	const first = includeAmounts.length > 0 ? includeAmounts[0] : excludeAmounts.length > 0 ? excludeAmounts[0] : 0;
+	let hasMixedAmounts = false;
+	for (const a of includeAmounts) if (Math.abs(a - first) > 1e-6) {
+		hasMixedAmounts = true;
+		break;
+	}
+	if (!hasMixedAmounts) {
+		for (const a of excludeAmounts) if (Math.abs(a - first) > 1e-6) {
+			hasMixedAmounts = true;
+			break;
 		}
 	}
-	return modified;
+	return {
+		amount: Math.max(0, Math.min(1, first)),
+		hasMixedAmounts
+	};
+}
+/**
+* Derive the auto scrim color from a normalized bg hex. Dark themes scrim
+* toward `DARK_SCRIM`; light themes scrim toward `LIGHT_SCRIM`. Returns
+* `null` when `bg` is absent or unparseable — signals legacy single-
+* channel fallback in `fadeCell`.
+*/
+function deriveAutoScrimColor(bg) {
+	if (!bg) return null;
+	const lum = relativeLuminance(bg);
+	if (lum === null) return null;
+	return lum < .18 ? DARK_SCRIM : LIGHT_SCRIM;
 }
-function collectBackdropMarkers(node, includes, excludes) {
+/**
+* Polarity detection for an arbitrary scrim color. Returns `true` when the
+* scrim is on the LIGHT side of the luminance threshold (fg should drift
+* toward white), `false` otherwise. Uses luminance, not string equality,
+* so tinted scrims (mid-gray neutrals, etc.) land on the correct branch.
+* Null scrim defaults to false (dark-theme fallback behavior).
+*/
+function isLightScrim(scrim) {
+	if (scrim === null) return false;
+	const lum = relativeLuminance(scrim);
+	if (lum === null) return false;
+	return lum >= DARK_LUMINANCE_THRESHOLD;
+}
+function collectBackdropMarkers(node, includes, excludes, includeAmounts, excludeAmounts) {
 	const props = node.props;
-	const includeRaw = props[FADE_ATTR];
-	const excludeRaw = props[FADE_EXCLUDE_ATTR];
+	const includeRaw = props[BACKDROP_FADE_ATTR];
+	const excludeRaw = props[BACKDROP_FADE_EXCLUDE_ATTR];
 	if (includeRaw !== void 0 || excludeRaw !== void 0) {
 		const rect = node.screenRect ?? node.scrollRect ?? node.boxRect;
 		if (rect && rect.width > 0 && rect.height > 0) {
 			const inc = parseFade(includeRaw);
-			if (inc !== null) includes.push({
-				rect,
-				amount: inc
-			});
+			if (inc !== null) {
+				includes.push({ rect });
+				includeAmounts.push(inc);
+			}
 			const exc = parseFade(excludeRaw);
-			if (exc !== null) excludes.push({
-				rect,
-				amount: exc
-			});
+			if (exc !== null) {
+				excludes.push({ rect });
+				excludeAmounts.push(exc);
+			}
 		}
 	}
-	for (const child of node.children) collectBackdropMarkers(child, includes, excludes);
+	for (const child of node.children) collectBackdropMarkers(child, includes, excludes, includeAmounts, excludeAmounts);
 }
+/**
+* Coerce a marker attribute value into a fade amount in (0, 1], or `null`
+* when the marker is absent / disabled.
+*
+* Accepted inputs:
+*
+*   - `undefined`, `null`, `false` → `null` (marker absent)
+*   - `true` → `DEFAULT_AMOUNT` (presence attribute, e.g. `<Backdrop fade />`)
+*   - `""` → `DEFAULT_AMOUNT` (HTML-attribute presence idiom)
+*   - finite numeric or numeric-string (including in scientific notation):
+*       - `<= 0` → `null` (explicit opt-out)
+*       - `> 1` → `1` (clamped)
+*       - otherwise → the numeric value itself
+*   - any other non-numeric string (e.g. `"bad"`) → `null`
+*
+* The presence-attribute idiom lets components emit `data-backdrop-fade`
+* without threading a numeric value through when the default is fine. The
+* React `Backdrop.tsx` / `ModalDialog.tsx` today always emit a numeric
+* attribute, but the semantic is forward-compatible so nothing breaks if
+* a future component (or a hand-written JSX usage) prefers presence-only.
+*/
 function parseFade(raw) {
 	if (raw === void 0 || raw === null) return null;
+	if (raw === false) return null;
+	if (raw === true) return DEFAULT_AMOUNT;
+	if (raw === "") return DEFAULT_AMOUNT;
 	const n = typeof raw === "number" ? raw : Number(raw);
 	if (!Number.isFinite(n)) return null;
 	if (n <= 0) return null;
 	return n > 1 ? 1 : n;
 }
-function fadeRect(buffer, rect, amount, strategy) {
-	const x0 = Math.max(0, rect.x);
-	const y0 = Math.max(0, rect.y);
-	const x1 = Math.min(buffer.width, rect.x + rect.width);
-	const y1 = Math.min(buffer.height, rect.y + rect.height);
-	if (x0 >= x1 || y0 >= y1) return false;
-	let any = false;
-	for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) if (fadeCell(buffer, x, y, amount, strategy)) any = true;
-	return any;
-}
-function fadeRectExcluding(buffer, outer, inner, amount, strategy) {
-	const ox0 = Math.max(0, outer.x);
-	const oy0 = Math.max(0, outer.y);
-	const ox1 = Math.min(buffer.width, outer.x + outer.width);
-	const oy1 = Math.min(buffer.height, outer.y + outer.height);
-	const ix0 = Math.max(ox0, inner.x);
-	const iy0 = Math.max(oy0, inner.y);
-	const ix1 = Math.min(ox1, inner.x + inner.width);
-	const iy1 = Math.min(oy1, inner.y + inner.height);
-	const innerValid = ix0 < ix1 && iy0 < iy1;
-	let any = false;
-	for (let y = oy0; y < oy1; y++) for (let x = ox0; x < ox1; x++) {
-		if (innerValid && x >= ix0 && x < ix1 && y >= iy0 && y < iy1) continue;
-		if (fadeCell(buffer, x, y, amount, strategy)) any = true;
-	}
-	return any;
+//#endregion
+//#region packages/ag-term/src/pipeline/backdrop/color-compat.ts
+/**
+* Backdrop fade — `@silvery/color` compatibility shim.
+*
+* Temporary shim while `@silvery/color` lags behind on publish cycles.
+* `@silvery/color` does export `mixSrgb` and `deemphasize` from source; this
+* module prefers the upstream versions at runtime and falls back to a
+* local implementation when an upstream export is missing — e.g., when a
+* new helper is introduced in the same release cycle as the silvery
+* package that imports it (the published `@silvery/color` dist doesn't
+* ship the new name until its next publish, breaking CI verify).
+*
+* The fallback implementations are byte-identical to the upstream ones.
+* Once all downstream consumers of silvery are on a published version of
+* `@silvery/color` that exports every name we reference, delete the
+* `local*` fallbacks and collapse each export to a direct re-export.
+*
+* Light-theme-aware deemphasize (`deemphasizeOklchToward`) is NOT in
+* upstream yet — it's only shipped by this module. When it lands in
+* `@silvery/color`, replace the local implementation with an upstream
+* re-export behind the same shim.
+*
+* @see ./color.ts for hex↔rgb adapter helpers and `HexColor` type.
+*/
+/**
+* sRGB source-over alpha mix. `out = a * (1 - t) + b * t`.
+*
+* Prefers `@silvery/color`'s published export; falls back to the local copy
+* when upstream doesn't ship the name yet. The local implementation matches
+* `@silvery/color/src/color.ts` byte-for-byte and is safe to use while the
+* publish train catches up.
+*/
+function localMixSrgb(a, b, t) {
+	const ra = hexToRgb$1(a);
+	const rb = hexToRgb$1(b);
+	if (!ra || !rb) return a;
+	const u = Math.max(0, Math.min(1, t));
+	return rgbToHex(ra.r * (1 - u) + rb.r * u, ra.g * (1 - u) + rb.g * u, ra.b * (1 - u) + rb.b * u);
+}
+/** sRGB source-over mix. Prefers upstream `@silvery/color`; falls back to the local copy. */
+const mixSrgb = Upstream.mixSrgb ?? localMixSrgb;
+/**
+* OKLCH-native deemphasize that drifts toward EITHER black (dark themes)
+* OR white (light themes). `towardLight` controls the lightness target;
+* the chroma falloff is identical in both directions.
+*
+*   towardLight=false (dark themes):
+*     L' = L × (1 - amount)          // linear toward black
+*   towardLight=true (light themes):
+*     L' = L + (1 - L) × amount      // linear toward white
+*   (both branches):
+*     C' = C × (1 - amount)²         // quadratic chroma falloff
+*     H' = H                         // hue preserved
+*
+* The asymmetric chroma falloff corrects for a perceptual nonlinearity:
+* the human visual system reads chroma RELATIVE to luminance, so a modest
+* OKLCH C at extreme L *appears* distinctly more chromatic than the same C
+* near mid-L. Proportional L+C scaling (`C *= 1-α`, preserving C/L) feels
+* "more saturated when darkened" to viewers — the exact complaint that
+* prompted the quadratic version.
+*
+* Using `(1-α)²` for chroma reduces saturation faster than lightness on
+* both polarities:
+*
+*   α=0.25 → C *= 0.563  (C/L drops to 75% of original)
+*   α=0.40 → C *= 0.360  (C/L drops to 60%)
+*   α=0.50 → C *= 0.250  (C/L drops to 50%)
+*   α=1.00 → C *= 0      (fully faded to the target luminance).
+*
+* Light-theme case (towardLight=true): a bright colored text on a light
+* backdrop is made paler by raising L toward 1 and dropping C — the
+* symmetric "fade toward the page color" behavior macOS ships in light
+* mode. Without the polarity flip, the dark-only formula `L *= (1 - α)`
+* would darken colored text on a light bg, which reads as "text popping"
+* against the faded scrim rather than receding.
+*/
+function localDeemphasizeOklchToward(hex, amount, towardLight) {
+	const o = upstreamHexToOklch(hex);
+	if (!o) return hex;
+	const a = Math.max(0, Math.min(1, amount));
+	const chromaFactor = (1 - a) * (1 - a);
+	const L = towardLight ? o.L + (1 - o.L) * a : o.L * (1 - a);
+	return upstreamOklchToHex({
+		L: Math.max(0, Math.min(1, L)),
+		C: Math.max(0, o.C * chromaFactor),
+		H: o.H
+	});
+}
+const upstreamHexToOklch = Upstream.hexToOklch;
+const upstreamOklchToHex = Upstream.oklchToHex;
+const deemphasizeOklchToward = Upstream.deemphasizeOklchToward ?? localDeemphasizeOklchToward;
+//#endregion
+//#region packages/ag-term/src/pipeline/backdrop/region.ts
+/**
+* Walk every cell covered by the plan's include and exclude rects and
+* invoke `visit(x, y)` for each unique cell.
+*
+* `includes` cells are those INSIDE any include rect.
+* `excludes` cells are those OUTSIDE any exclude rect (i.e., excluded from
+* the exclude's interior — the modal "cuts a hole" pattern).
+*
+* Rects are clipped to the buffer bounds (`[0, bufferWidth)` ×
+* `[0, bufferHeight)`). Zero-size rects are skipped. Cells are deduped
+* across all rects via a `Uint8Array` bitset — a cell belonging to two
+* overlapping includes is visited once, not twice.
+*
+* Returns the count of unique cells visited. Useful for short-circuiting
+* the "was any cell modified?" signal in realizers.
+*/
+function forEachFadeRegionCell(bufferWidth, bufferHeight, includes, excludes, visit) {
+	if (bufferWidth <= 0 || bufferHeight <= 0) return 0;
+	if (includes.length === 0 && excludes.length === 0) return 0;
+	const seen = new Uint8Array(bufferWidth * bufferHeight);
+	let count = 0;
+	const once = (x, y) => {
+		const i = y * bufferWidth + x;
+		if (seen[i] !== 0) return;
+		seen[i] = 1;
+		count += 1;
+		visit(x, y);
+	};
+	for (const { rect } of includes) {
+		const x0 = Math.max(0, rect.x);
+		const y0 = Math.max(0, rect.y);
+		const x1 = Math.min(bufferWidth, rect.x + rect.width);
+		const y1 = Math.min(bufferHeight, rect.y + rect.height);
+		if (x0 >= x1 || y0 >= y1) continue;
+		for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) once(x, y);
+	}
+	if (excludes.length > 0) {
+		const clipped = [];
+		for (const { rect } of excludes) {
+			const x0 = Math.max(0, rect.x);
+			const y0 = Math.max(0, rect.y);
+			const x1 = Math.min(bufferWidth, rect.x + rect.width);
+			const y1 = Math.min(bufferHeight, rect.y + rect.height);
+			if (x0 < x1 && y0 < y1) clipped.push({
+				x0,
+				y0,
+				x1,
+				y1
+			});
+		}
+		if (clipped.length > 0) for (let y = 0; y < bufferHeight; y++) for (let x = 0; x < bufferWidth; x++) {
+			let insideAnyExclude = false;
+			for (const r of clipped) if (x >= r.x0 && x < r.x1 && y >= r.y0 && y < r.y1) {
+				insideAnyExclude = true;
+				break;
+			}
+			if (!insideAnyExclude) once(x, y);
+		}
+		else for (let y = 0; y < bufferHeight; y++) for (let x = 0; x < bufferWidth; x++) once(x, y);
+	}
+	return count;
+}
+//#endregion
+//#region packages/ag-term/src/pipeline/backdrop/realize-buffer.ts
+/**
+* Stage 2a — apply the plan's cell-level transform to the buffer.
+*
+* Walks every include + exclude cell once via `forEachFadeRegionCell` and
+* applies `fadeCell` with the plan's single `amount`. The buffer is mutated
+* in place.
+*
+* When `plan.kittyEnabled === true`, emoji cells (detected via
+* `isLikelyEmoji(cell.char)`) are SKIPPED — the Kitty overlay realizer
+* composites the scrim on top of the unmixed cell. When
+* `plan.kittyEnabled === false`, emoji cells go through the per-cell mix
+* AND get SGR 2 (`attrs.dim`) stamped on lead + continuation.
+*
+* Returns `true` when at least one buffer cell was mutated.
+*/
+function realizeToBuffer(plan, buffer) {
+	if (!plan.active) return false;
+	if (plan.amount <= 0) return false;
+	let modified = false;
+	forEachFadeRegionCell(buffer.width, buffer.height, plan.includes, plan.excludes, (x, y) => {
+		if (fadeCell(buffer, x, y, plan)) modified = true;
+	});
+	return modified;
 }
 /**
 * Fade a single cell. Returns true if the cell was modified.
 *
-* - `blend` strategy: mix fg toward bg in OKLab. When either color is null or
-*   the default-bg sentinel, also stamps `dim`.
-* - `dim` strategy: stamp `dim` attribute.
+* Two-channel transform (see `./plan.ts` for the full color model):
+*
+*   fg' = deemphasizeOklchToward(fg, amount, scrimTowardLight)
+*   bg' = mixSrgb(bg, scrim, amount)
 *
-* Wide-char continuation cells are skipped — they share styling with the
-* leading cell and modifying them separately would desync.
+* Fg uses OKLCH deemphasize (not sRGB mixing) so colored text deemphasizes
+* perceptually — pale lavender becomes dull slate on dark themes, pale
+* grey on light themes. The polarity flag `scrimTowardLight` (from the
+* plan) steers L toward 0 or 1; chroma falloff is symmetric. Bg uses sRGB
+* source-over because the Kitty graphics scrim overlay composites in sRGB
+* at alpha at the hardware level.
+*
+* `null`/`DEFAULT_BG` cells are resolved to `plan.defaultBg` first (that
+* IS the color the terminal paints), then mixed toward the scrim — so
+* empty cells darken at the same rate as explicitly-colored cells.
+*
+* Uniform amounts for fg + bg preserve relative brightness ordering across
+* borders vs fills. Heaviness is controlled by `plan.amount` (default
+* 0.25, calibrated against macOS 0.20, Material 3 0.32, iOS 0.40, Flutter
+* 0.54).
+*
+* The `scrim !== null` gate activates the full two-channel path: fg always
+* deemphasizes, and bg mixes toward the scrim when a resolvable bg hex is
+* available (`cell.bg` non-null OR `defaultBg` non-null). When both
+* `scrim` and a resolvable bg are null (no theme context at all): falls
+* back to mixing fg toward `cell.bg` so the cell still reads as "receded"
+* without needing external theme info.
+*
+* ### Wide-char / emoji handling
+*
+* Terminals render emoji using the glyph's own bitmap colors — the fg mix
+* has no visible effect on the emoji glyph. Two paths, mutually exclusive:
+*
+* 1. Kitty graphics available: `fadeCell` SKIPS emoji wide cells entirely.
+*    The Kitty overlay composites the scrim at alpha=amount on top, landing
+*    at `cell * (1 - amount) + scrim * amount` — same as surrounding cells.
+* 2. Kitty unavailable: mix the cell bg + stamp `attrs.dim` on lead +
+*    continuation. Terminals honoring SGR 2 on emoji fade the glyph. Wide
+*    TEXT (CJK etc.) goes through the normal deemphasize path on both
+*    branches — the fg mix works fine and SGR 2 on CJK over-fades.
 */
-function fadeCell(buffer, x, y, amount, strategy) {
+function fadeCell(buffer, x, y, plan) {
 	if (buffer.isCellContinuation(x, y)) return false;
 	const cell = buffer.getCell(x, y);
-	if (strategy === "dim") {
+	const isEmojiGlyph = cell.wide && isLikelyEmoji(cell.char ?? "");
+	if (plan.kittyEnabled && isEmojiGlyph) return false;
+	const { amount, scrim, defaultBg, defaultFg, scrimTowardLight } = plan;
+	const rawFgHex = colorToHex(cell.fg);
+	if (scrim !== null) {
+		const fgHex = rawFgHex ?? defaultFg ?? (scrimTowardLight ? "#000000" : "#ffffff");
+		const bgHex = colorToHex(cell.bg) ?? defaultBg;
+		const mixedBgHex = bgHex !== null ? mixSrgb(bgHex, scrim, amount) : null;
+		const mixedBg = mixedBgHex !== null ? hexToRgb$1(mixedBgHex) : null;
+		const stampEmojiDim = isEmojiGlyph;
+		const newAttrs = stampEmojiDim && !cell.attrs.dim ? {
+			...cell.attrs,
+			dim: true
+		} : cell.attrs;
+		const mixedFg = hexToRgb$1(deemphasizeOklchToward(fgHex, amount, scrimTowardLight));
+		if (mixedFg) {
+			if (mixedBg) {
+				buffer.setCell(x, y, {
+					...cell,
+					fg: mixedFg,
+					bg: mixedBg,
+					attrs: newAttrs
+				});
+				propagateToContinuation(buffer, cell, x, y, {
+					bg: mixedBg,
+					dim: stampEmojiDim
+				});
+				return true;
+			}
+			buffer.setCell(x, y, {
+				...cell,
+				fg: mixedFg,
+				attrs: newAttrs
+			});
+			if (stampEmojiDim) propagateToContinuation(buffer, cell, x, y, { dim: true });
+			return true;
+		}
+		if (mixedBg) {
+			buffer.setCell(x, y, {
+				...cell,
+				bg: mixedBg,
+				attrs: newAttrs
+			});
+			propagateToContinuation(buffer, cell, x, y, {
+				bg: mixedBg,
+				dim: stampEmojiDim
+			});
+			return true;
+		}
 		if (cell.attrs.dim) return false;
 		buffer.setCell(x, y, {
 			...cell,
@@ -4149,14 +4746,14 @@ function fadeCell(buffer, x, y, amount, strategy) {
 		});
 		return true;
 	}
-	const fgHex = colorToHex(cell.fg);
+	const fgHex = rawFgHex;
 	const bgHex = colorToHex(cell.bg);
 	if (fgHex && bgHex) {
-		const blendedRgb = hexToRgb(blend(fgHex, bgHex, amount));
-		if (!blendedRgb) return false;
+		const mixedRgb = hexToRgb$1(mixSrgb(fgHex, bgHex, amount));
+		if (!mixedRgb) return false;
 		buffer.setCell(x, y, {
 			...cell,
-			fg: blendedRgb
+			fg: mixedRgb
 		});
 		return true;
 	}
@@ -4168,42 +4765,167 @@ function fadeCell(buffer, x, y, amount, strategy) {
 			dim: true
 		}
 	});
+	if (cell.wide && x + 1 < buffer.width) {
+		const cont = buffer.getCell(x + 1, y);
+		if (!cont.attrs.dim) buffer.setCell(x + 1, y, {
+			...cont,
+			attrs: {
+				...cont.attrs,
+				dim: true
+			}
+		});
+	}
 	return true;
 }
-/** Convert a buffer Color to a `#rrggbb` hex string, or null if unresolvable. */
-function colorToHex(color) {
-	if (color === null) return null;
-	if (typeof color === "number") {
-		const rgb = ansi256ToRgb(color);
-		return rgbToHex(rgb.r, rgb.g, rgb.b);
-	}
-	if (isDefaultBg(color)) return null;
-	return rgbToHex(color.r, color.g, color.b);
+/**
+* Propagate lead-cell updates to the continuation cell of a wide char.
+*
+* When a wide char (emoji, CJK) has its bg or dim attribute changed on the
+* lead cell, the continuation cell at `x+1` must track in lockstep or the
+* two halves of the glyph render inconsistently (different bg → visually
+* split glyph; missing dim → half-faded emoji).
+*
+* `patch.bg` copies the mixed bg onto the continuation. `patch.dim` stamps
+* `attrs.dim`. Either or both may be provided; the function is a no-op
+* when neither is set.
+*/
+function propagateToContinuation(buffer, leadCell, x, y, patch) {
+	if (!leadCell.wide) return;
+	if (x + 1 >= buffer.width) return;
+	const cont = buffer.getCell(x + 1, y);
+	if (!cont.continuation) return;
+	const stampDim = patch.dim === true && !cont.attrs.dim;
+	const writeBg = patch.bg !== void 0;
+	if (!stampDim && !writeBg) return;
+	const attrs = stampDim ? {
+		...cont.attrs,
+		dim: true
+	} : cont.attrs;
+	if (writeBg) buffer.setCell(x + 1, y, {
+		...cont,
+		bg: patch.bg,
+		attrs
+	});
+	else buffer.setCell(x + 1, y, {
+		...cont,
+		attrs
+	});
 }
-function rgbToHex(r, g, b) {
-	const clamp = (n) => {
-		return Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, "0");
+//#endregion
+//#region packages/ag-term/src/pipeline/backdrop/realize-kitty.ts
+init_src();
+/**
+* Stage 2b — emit the Kitty graphics overlay for the plan.
+*
+* The output always begins with `CURSOR_SAVE + kittyDeleteAllScrimPlacements()
+* + CURSOR_RESTORE` when `plan.active` is true — even when zero emoji cells
+* fall inside the faded region this frame. The unconditional clear is what
+* erases stale placements from a previous frame.
+*
+* Returns `""` when `plan.active` is false. Callers that also need to
+* suppress the overlay because Kitty graphics are not available should NOT
+* call this function at all — the orchestrator (`./index.ts`) guards the
+* call site with `plan.kittyEnabled`.
+*/
+function realizeToKitty(plan, buffer) {
+	if (!plan.active) return "";
+	const cells = collectEmojiCellsInFadeRegion(buffer, plan);
+	const tint = hexToRgb$1(plan.scrim ?? plan.defaultBg ?? "#000000") ?? {
+		r: 0,
+		g: 0,
+		b: 0
 	};
-	return `#${clamp(r)}${clamp(g)}${clamp(b)}`;
+	const scrimAlpha = Math.max(0, Math.min(255, Math.round(plan.amount * 255)));
+	const parts = [];
+	parts.push("\x1B7");
+	if (cells.length === 0) {
+		parts.push(kittyDeleteAllScrimPlacements());
+		parts.push("\x1B8");
+		return parts.join("");
+	}
+	const pixels = buildScrimPixels(tint, scrimAlpha);
+	parts.push(kittyUploadScrimImage(pixels, 2, 2));
+	parts.push(kittyDeleteAllScrimPlacements());
+	for (const { x, y } of cells) {
+		parts.push(cupTo(x, y));
+		parts.push(kittyPlaceAt({
+			placementId: backdropPlacementId(x, y),
+			cols: 2,
+			rows: 1,
+			z: 1
+		}));
+	}
+	parts.push("\x1B8");
+	return parts.join("");
 }
-function hexToRgb(hex) {
-	if (typeof hex !== "string") return null;
-	let s = hex;
-	if (s.startsWith("#")) s = s.slice(1);
-	if (s.length === 3) s = s[0] + s[0] + s[1] + s[1] + s[2] + s[2];
-	if (s.length !== 6) return null;
-	const r = parseInt(s.slice(0, 2), 16);
-	const g = parseInt(s.slice(2, 4), 16);
-	const b = parseInt(s.slice(4, 6), 16);
-	if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) return null;
+/**
+* Collect the coordinates of every EMOJI lead cell inside the plan's faded
+* region. CJK and other wide TEXT cells are excluded — they respond to fg
+* color mixing like normal text and don't need the Kitty overlay. Only
+* bitmap-glyph cells (detected via `isLikelyEmoji(cell.char)`) need an
+* overlay because their rendering ignores the fg color.
+*
+* The iteration order is deterministic (delegated to
+* `forEachFadeRegionCell`), matching the buffer realizer's order. STRICT
+* mode compares the overlay string across fresh and incremental paths —
+* any drift in this order would fail the comparison.
+*/
+function collectEmojiCellsInFadeRegion(buffer, plan) {
+	const out = [];
+	forEachFadeRegionCell(buffer.width, buffer.height, plan.includes, plan.excludes, (x, y) => {
+		if (x + 1 >= buffer.width) return;
+		if (!buffer.isCellWide(x, y)) return;
+		if (buffer.isCellContinuation(x, y)) return;
+		if (!isLikelyEmoji(buffer.getCell(x, y).char ?? "")) return;
+		out.push({
+			x,
+			y
+		});
+	});
+	return out;
+}
+//#endregion
+//#region packages/ag-term/src/pipeline/backdrop/index.ts
+const EMPTY_RESULT = Object.freeze({
+	modified: false,
+	overlay: ""
+});
+/**
+* Apply backdrop-fade to the buffer based on tree markers.
+*
+* Thin orchestrator over the mask → realize stages:
+*
+*   plan = buildPlan(root, options)
+*   modified = realizeToBuffer(plan, buffer)
+*   overlay = plan.kittyEnabled ? realizeToKitty(plan, buffer) : ""
+*
+* Returns a `BackdropResult`:
+* - `modified` — any buffer cells changed.
+* - `overlay` — out-of-band ANSI escapes. Non-empty only when the plan is
+*   active AND Kitty graphics are enabled. An active overlay always begins
+*   with a delete-all command so last-frame placements get erased even if
+*   this frame has no wide cells.
+*
+* **Inactive frames are silent.** When `plan.active` is false this returns
+* `EMPTY_RESULT` regardless of `options.kittyGraphics`. Stale scrim
+* placements from a prior active frame must be cleaned up at the
+* deactivation EDGE by the caller (e.g., `ag.ts` tracks `_kittyActive`
+* across frames and emits a one-shot delete-all when active→inactive).
+* Emitting the delete-all every inactive frame here would spam the
+* terminal — Modal's default `fade={0}` would push a cleanup string every
+* frame indefinitely.
+*/
+function applyBackdrop(root, buffer, options) {
+	const plan = buildPlan(root, options);
+	if (plan.mixedAmounts && process.env.NODE_ENV !== "production") console.warn(`[silvery:backdrop] multiple fade amounts in one frame (using ${plan.amount}); Kitty overlay will use the first observed amount. See plan.ts / assertSingleAmount.`);
+	if (!plan.active) return EMPTY_RESULT;
 	return {
-		r,
-		g,
-		b
+		modified: realizeToBuffer(plan, buffer),
+		overlay: plan.kittyEnabled ? realizeToKitty(plan, buffer) : ""
 	};
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.122.0/helpers/usingCtx.js
+//#region \0@oxc-project+runtime@0.126.0/helpers/usingCtx.js
 function _usingCtx() {
 	var r = "function" == typeof SuppressedError ? SuppressedError : function(r, e) {
 		var n = Error();
@@ -4278,13 +5000,78 @@ function _usingCtx() {
 * ```
 */
 init_buffer();
+init_src();
 const log = createLogger("silvery:render");
 const baseLog = createLogger("@silvery/ag-react");
+/**
+* Walk the ag tree top-down to find the root ThemeProvider's background color.
+*
+* ThemeProvider in @silvery/ag-react renders a `<Box theme={merged}>` wrapper.
+* The render phase pushes/pops this theme via pushContextTheme/popContextTheme,
+* so the module-level theme stack is empty after the render phase completes.
+* We walk the tree directly to recover the root bg without requiring the
+* render phase to be running.
+*
+* Returns the first Box node's Sterling `bg-surface-default` (with legacy `bg`
+* fallback for backdrop-only Themes that pre-date Sterling's flat surface
+* tokens) found in a depth-first walk, or `null` if no theme node is present
+* (bare tests without ThemeProvider).
+*/
+function findRootThemeBg(root) {
+	const props = root.props;
+	if (props.theme) {
+		const theme = props.theme;
+		const sterlingBg = theme["bg-surface-default"];
+		if (typeof sterlingBg === "string") return sterlingBg;
+		const legacyBg = theme["bg"];
+		if (typeof legacyBg === "string") return legacyBg;
+	}
+	for (const child of root.children) {
+		const found = findRootThemeBg(child);
+		if (found !== null) return found;
+	}
+	return null;
+}
+/**
+* Env heuristic: should the backdrop-fade pass emit Kitty graphics overlays?
+*
+* This is the MVP gate — a lightweight capability detector used when the
+* caller doesn't pass `kittyGraphics` explicitly. Matches the Option C design
+* intent: emit only on modern terminals where Kitty graphics are known to
+* work (Kitty, Ghostty, WezTerm), NOT inside tmux (DCS passthrough is
+* unreliable), with an explicit `SILVERY_KITTY_GRAPHICS` override.
+*
+* - `SILVERY_KITTY_GRAPHICS=0` → always off
+* - `SILVERY_KITTY_GRAPHICS=1` → always on (bypasses tmux + term checks)
+* - `TMUX` env var present → off (unless forced on above)
+* - `TERM_PROGRAM` in {Ghostty, WezTerm} → on
+* - `TERM` contains "kitty" → on
+* - `KITTY_WINDOW_ID` set → on
+* - otherwise → off
+*
+* The long-term plan is to promote this to a `TerminalCaps.kittyGraphics`
+* consumer. That field exists (see `@silvery/ansi` detectTerminalCaps) but
+* isn't threaded into the render pipeline yet — tracked as a follow-up.
+*/
+function isKittyGraphicsEnabledFromEnv() {
+	const env = typeof process !== "undefined" ? process.env : {};
+	const override = env.SILVERY_KITTY_GRAPHICS;
+	if (override === "0" || override === "false") return false;
+	if (override === "1" || override === "true") return true;
+	if (env.TMUX) return false;
+	const program = env.TERM_PROGRAM ?? "";
+	if (program === "ghostty" || program === "Ghostty" || program === "WezTerm") return true;
+	if ((env.TERM ?? "").includes("kitty")) return true;
+	if (env.KITTY_WINDOW_ID) return true;
+	return false;
+}
 function createAg(root, options) {
 	const measurer = options?.measurer;
 	const colorLevel = options?.colorLevel ?? "truecolor";
+	const kittyGraphics = options?.kittyGraphics !== void 0 ? options.kittyGraphics : isKittyGraphicsEnabledFromEnv();
 	const ctx = measurer ? { measurer } : void 0;
 	let _prevBuffer = null;
+	let _kittyActive = false;
 	let hasScroll = false;
 	let hasSticky = false;
 	function doLayout(cols, rows, opts) {
@@ -4411,14 +5198,24 @@ function createAg(root, options) {
 			log.debug?.(`content: ${tContent.toFixed(2)}ms`);
 		}
 		let carryForwardBuffer;
-		if (hasBackdropMarkers(root)) {
+		let overlay = "";
+		const backdropActive = hasBackdropMarkers(root);
+		if (backdropActive) {
 			carryForwardBuffer = buffer.clone();
 			if (!opts?.fresh) _prevBuffer = carryForwardBuffer;
-			applyBackdropFade(root, buffer, { colorLevel });
+			const defaultBg = findRootThemeBg(root) ?? void 0;
+			overlay = applyBackdrop(root, buffer, {
+				colorLevel,
+				defaultBg,
+				kittyGraphics
+			}).overlay;
 		} else {
 			carryForwardBuffer = buffer;
 			if (!opts?.fresh) _prevBuffer = buffer;
 		}
+		const kittyActiveThisFrame = backdropActive && overlay.length > 0;
+		if (_kittyActive && !kittyActiveThisFrame) overlay = "\x1B7" + kittyDeleteAllScrimPlacements() + "\x1B8";
+		_kittyActive = kittyActiveThisFrame;
 		clearDirtyTracking();
 		const acc = globalThis.__silvery_bench_phases;
 		if (acc) {
@@ -4430,7 +5227,8 @@ function createAg(root, options) {
 			buffer,
 			carryForwardBuffer,
 			prevBuffer,
-			tContent
+			tContent,
+			overlay
 		};
 	}
 	function agCreateNode(type, props) {
@@ -4482,7 +5280,8 @@ function createAg(root, options) {
 				frame: result.frame,
 				buffer: result.buffer,
 				carryForwardBuffer: result.carryForwardBuffer,
-				prevBuffer: result.prevBuffer
+				prevBuffer: result.prevBuffer,
+				overlay: result.overlay
 			};
 		},
 		resetBuffer() {
@@ -4563,7 +5362,7 @@ init_buffer();
 let engineInitialized = false;
 async function ensureLayoutEngine() {
 	if (engineInitialized || isLayoutEngineInitialized()) return;
-	const { ensureDefaultLayoutEngine } = await import("./layout-engine--drvrWjD.mjs");
+	const { ensureDefaultLayoutEngine } = await import("./layout-engine-B6Cdz1yZ.mjs");
 	await ensureDefaultLayoutEngine();
 	engineInitialized = true;
 }
@@ -4710,6 +5509,6 @@ function withActEnvironment(fn) {
 	}
 }
 //#endregion
-export { _usingCtx as i, renderStringSync as n, createAg as r, renderString as t };
+export { setActiveColorLevel as a, _usingCtx as i, renderStringSync as n, createAg as r, renderString as t };
 
-//# sourceMappingURL=render-string-DVfgc8xr.mjs.map
+//# sourceMappingURL=render-string-X-CxpTdZ.mjs.map