Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Panels: keep text readable on translucent surfaces (#11307) (#12985)

Nathan Daneea4513728bdc
diff --git a/crates/engine/src/panels/tests.rs b/crates/engine/src/panels/tests.rs
index 3f4e0c008f..c36d3ec2da 100644
--- a/crates/engine/src/panels/tests.rs
+++ b/crates/engine/src/panels/tests.rs
@@ -762,6 +762,27 @@ fn surface_precedence_and_truthful_contrast_fallback_have_wire_contracts() {
let mut opaque = spec.clone();
opaque.surface = PanelSurface::Opaque;
assert_eq!(group_surface(Zone::Left, [&spec, &opaque]), PanelSurface::Opaque);
+ let mut follow = spec.clone();
+ follow.surface = PanelSurface::FollowZone;
+ follow.text_heavy = false;
+ let mut text_heavy = follow.clone();
+ text_heavy.text_heavy = true;
+ for zone in [Zone::Left, Zone::Right, Zone::Floating, Zone::Bottom, Zone::Window] {
+ assert_eq!(group_surface(zone, [&spec, &opaque]), PanelSurface::Opaque);
+ assert_eq!(group_surface(zone, [&opaque, &spec]), PanelSurface::Opaque);
+ assert_eq!(group_surface(zone, [&follow, &text_heavy]), PanelSurface::Opaque);
+ assert_eq!(group_surface(zone, [&text_heavy, &follow]), PanelSurface::Opaque, "inactive metadata cannot depend on tab order");
+ assert_eq!(
+ group_surface(zone, [&text_heavy, &spec]),
+ PanelSurface::Translucent,
+ "explicit translucency overrides both text-heavy and zone defaults"
+ );
+ assert_eq!(group_surface(zone, [&spec, &text_heavy]), PanelSurface::Translucent);
+ assert_eq!(
+ group_surface(zone, [&follow]),
+ if matches!(zone, Zone::Bottom | Zone::Window) { PanelSurface::Opaque } else { PanelSurface::Translucent }
+ );
+ }
let outcome = ContrastOutcome::RetainReadableFallback { reason: ContrastFailure::UnreadableAtFullOpacity };
let roundtrip: ContrastOutcome = serde_json::from_value(serde_json::to_value(&outcome).unwrap()).unwrap();
assert_eq!(roundtrip, outcome);
diff --git a/crates/ui-egui/src/colour_tokens_tests.rs b/crates/ui-egui/src/colour_tokens_tests.rs
index 4dbc59d679..50f87e0525 100644
--- a/crates/ui-egui/src/colour_tokens_tests.rs
+++ b/crates/ui-egui/src/colour_tokens_tests.rs
@@ -217,6 +217,9 @@ fn colours_outside_the_theme_are_only_the_listed_neutral_ones() {
continue;
}
let src = std::fs::read_to_string(&path).unwrap();
+ if src.trim_start().starts_with("#![cfg(test)]") {
+ continue;
+ }
let code = src.split("#[cfg(test)]").next().unwrap_or(&src);
let n: usize = COLOUR_LITERALS.iter().map(|p| code.matches(p).count()).sum();
let allowed = ALLOWED_LITERALS.iter().find(|(f, _, _)| *f == relative).map_or(0, |(_, n, _)| *n);
diff --git a/crates/ui-egui/src/control.rs b/crates/ui-egui/src/control.rs
index 10e96890da..88d740e4b3 100644
--- a/crates/ui-egui/src/control.rs
+++ b/crates/ui-egui/src/control.rs
@@ -27,7 +27,7 @@
//! section the viewport shows (no window needed); the ground grid and the origin's axes as the
//! window shows them, unless `grid` or `axes` says
//! - `ui.icon_audit {reset?, stop?}`: collect/drain requested icon names, resolved masters and placeholder flags;
-//! - `ui.panel_fixture {enabled?, preset?}`: opt-in synthetic content in the real panel host;
+//! - `ui.panel_fixture {enabled?, preset?, translucency_percent?}`: opt-in synthetic content in the real panel host;
//! `{}` observes the current host, probe and Session without ticking or model commands
//! - `ui.menu {x?, y?, target?, close?}`: open a context menu at a point (the viewport's marking
//! menu, or a browser menu with `target: {type: body|sketch|component, …}`); without a point,
@@ -1890,6 +1890,12 @@ mod tests {
json!({"preset":"x".repeat(4096)}),
json!({"enabled":false,"preset":"docks"}),
json!({"enabled":true,"unknown":0}),
+ json!({"preset":"surfaces","translucency_percent":-1}),
+ json!({"preset":"surfaces","translucency_percent":101}),
+ json!({"preset":"surfaces","translucency_percent":"50"}),
+ json!({"preset":"surfaces","translucency_percent":null}),
+ json!({"translucency_percent":50}),
+ json!({"enabled":false,"translucency_percent":50}),
] {
assert!(crate::panel_runtime::control_specimen(&mut app, &params).is_err(), "{params}");
assert!(app.panel_runtime().is_none());
@@ -1917,6 +1923,7 @@ mod tests {
("stack_tabs", 4),
("content_fill", 2),
("inline", 1),
+ ("surfaces", 6),
] {
let before = crate::panel_runtime::inspect_host_specimen(&mut h.app).unwrap()["session"].clone();
h.step(&json!({"panel_fixture":{"enabled":true,"preset":name}})).unwrap();
@@ -1939,6 +1946,84 @@ mod tests {
}
}
+ #[test]
+ fn panel_surface_fixture_converts_translucency_without_saving_preferences() {
+ for percent in [0, 50, 100] {
+ let mut h = crate::scenario::Harness::new();
+ let preferences = serde_json::to_value(&h.app.preferences).unwrap();
+ crate::panel_runtime::control_specimen(&mut h.app, &json!({"preset":"surfaces","translucency_percent":percent})).unwrap();
+ h.frames(4);
+ let reply = crate::panel_runtime::inspect_host_specimen(&mut h.app).unwrap();
+ let sections = reply["host"]["sections"].as_array().unwrap();
+ assert!(!sections.is_empty());
+ for section in sections {
+ let alpha = section["paint_alpha"].as_u64().unwrap();
+ assert!(
+ alpha >= ((100 - percent) as f64 * 255.0 / 100.0).ceil() as u64,
+ "readability protection can only increase the requested opacity: {section}"
+ );
+ assert!(!section["contrast"].is_null(), "every painted surface reports its contrast decision");
+ }
+ assert_eq!(serde_json::to_value(&h.app.preferences).unwrap(), preferences);
+ }
+ }
+
+ #[test]
+ fn panel_fixture_live_opacity_updates_retain_controllers_layout_and_document() {
+ let mut h = crate::scenario::Harness::new();
+ crate::panel_runtime::control_specimen(&mut h.app, &json!({"preset":"surfaces","translucency_percent":0})).unwrap();
+ h.frames(4);
+ let document = h.app.session.doc.clone();
+ let model = h.app.session.model.state();
+ let camera = h.app.cam;
+ let preferences = serde_json::to_value(&h.app.preferences).unwrap();
+ let before = crate::panel_runtime::inspect_host_specimen(&mut h.app).unwrap();
+ let sections = h
+ .app
+ .universal_panel_frame()
+ .unwrap()
+ .layout
+ .sections
+ .iter()
+ .map(|section| (section.section.clone(), section.outer, section.body, section.surface))
+ .collect::<Vec<_>>();
+ for percent in [50, 100, 0] {
+ let prior = crate::panel_runtime::inspect_host_specimen(&mut h.app).unwrap();
+ let updated = crate::panel_runtime::control_specimen(&mut h.app, &json!({"translucency_percent":percent})).unwrap();
+ assert_eq!(updated["runtime"], prior["runtime"], "updating opacity does not tick, dispatch or replace content");
+ h.frames(4);
+ let after = crate::panel_runtime::inspect_host_specimen(&mut h.app).unwrap();
+ assert_eq!(after["runtime"]["layout"], before["runtime"]["layout"]);
+ for (old, new) in
+ before["runtime"]["probe"]["controllers"].as_array().unwrap().iter().zip(after["runtime"]["probe"]["controllers"].as_array().unwrap())
+ {
+ assert_eq!(new["controller_identity"], old["controller_identity"]);
+ assert_eq!(new["draft"], old["draft"]);
+ assert_eq!(new["transaction_live"], old["transaction_live"]);
+ }
+ assert_eq!(
+ h.app
+ .universal_panel_frame()
+ .unwrap()
+ .layout
+ .sections
+ .iter()
+ .map(|section| (section.section.clone(), section.outer, section.body, section.surface))
+ .collect::<Vec<_>>(),
+ sections
+ );
+ assert!(std::sync::Arc::ptr_eq(&document, &h.app.session.doc));
+ assert!(std::sync::Arc::ptr_eq(&model, &h.app.session.model.state()));
+ assert_eq!(h.app.cam, camera);
+ assert_eq!(serde_json::to_value(&h.app.preferences).unwrap(), preferences);
+ if percent == 0 {
+ assert!(h.app.universal_panel_frame().unwrap().layout.sections.iter().all(|section| section.paint_alpha == Some(255)));
+ }
+ }
+ h.app.disable_universal_panel_host().unwrap();
+ assert!(crate::panel_runtime::control_specimen(&mut h.app, &json!({"translucency_percent":50})).is_err());
+ }
+
#[test]
fn panel_fixture_teardown_honors_live_editor_guard_atomically() {
fn click_visible_guard(h: &mut crate::scenario::Harness, guard: &str) {
diff --git a/crates/ui-egui/src/panel_runtime/app.rs b/crates/ui-egui/src/panel_runtime/app.rs
index 86baff8f5b..183b43727d 100644
--- a/crates/ui-egui/src/panel_runtime/app.rs
+++ b/crates/ui-egui/src/panel_runtime/app.rs
@@ -419,6 +419,9 @@ impl AppPanelRuntime {
self.host = Some(WorkspacePanelHost::new(options)?);
Ok(())
}
+ pub fn set_requested_opacity(&mut self, opacity: Option<f32>) -> PanelResult<()> {
+ self.host.as_mut().ok_or_else(|| error(Rule::Lifecycle, "universal panel host disabled"))?.set_requested_opacity(opacity)
+ }
pub fn disable_host(&mut self) -> PanelResult<()> {
if self.host.is_some() {
self.with_adapters(|runtime, _native, services| runtime.mount_in_app(&ResolvedLayout::default(), &mut EmptyPanelHost, services))?;
@@ -1007,11 +1010,12 @@ impl crate::SolveApp {
.filter(|bounds| bounds.is_positive() && bounds.is_finite())
.map(logical_rect)
.collect();
+ let force_opaque = self.services.reduce_transparency.as_ref().and_then(|read| read(true)) == Some(true);
let prepared = match &mut self.panel_runtime {
Some(integration) => {
let result = (|| {
if let Some(host) = &mut integration.host {
- host.note_egui_context(ui.ctx());
+ host.note_egui_context(ui.ctx(), force_opaque);
host.set_gap(gap)?;
}
integration.prepare_host_in_domain(&self.session, logical_rect(render_domain), logical_rect(placement), &chrome)
diff --git a/crates/ui-egui/src/panel_runtime/layout.rs b/crates/ui-egui/src/panel_runtime/layout.rs
index efea6756d8..850d894331 100644
--- a/crates/ui-egui/src/panel_runtime/layout.rs
+++ b/crates/ui-egui/src/panel_runtime/layout.rs
@@ -5,6 +5,7 @@ use std::collections::{BTreeMap, BTreeSet};
use solidcraft_engine::panels::*;
+use super::HostSurfaceStyle;
use super::interaction::{HostPointerTarget, HostProposalSnapshot, HostResizeEdge};
/// Compatibility constant only; the host never allocates rails.
@@ -568,6 +569,10 @@ pub struct HostSurfaceAlpha {
#[derive(Clone, Debug)]
pub struct HostGeometryPolicy {
pub surface_alpha: Option<HostSurfaceAlpha>,
+ /// Captured renderer state; never written into a layout envelope.
+ pub surfaces: Option<HostSurfaceStyle>,
+ /// Runtime normalized opacity override; None retains authored theme opacity.
+ pub requested_opacity: Option<f32>,
pub default_opaque: bool,
pub effective_surfaces: BTreeMap<SectionId, PanelSurface>,
pub content: Vec<SideContentMeasure>,
@@ -579,7 +584,9 @@ pub struct HostGeometryPolicy {
impl PartialEq for HostGeometryPolicy {
fn eq(&self, other: &Self) -> bool {
- self.surface_alpha == other.surface_alpha
+ self.surfaces == other.surfaces
+ && self.requested_opacity.map(f32::to_bits) == other.requested_opacity.map(f32::to_bits)
+ && self.surface_alpha == other.surface_alpha
&& self.default_opaque == other.default_opaque
&& self.effective_surfaces == other.effective_surfaces
&& self.identity_reservations == other.identity_reservations
@@ -598,6 +605,8 @@ impl Default for HostGeometryPolicy {
fn default() -> Self {
Self {
surface_alpha: None,
+ surfaces: None,
+ requested_opacity: None,
default_opaque: true,
effective_surfaces: BTreeMap::new(),
content: Vec::new(),
@@ -625,6 +634,7 @@ pub struct HostTab {
#[derive(Clone, Debug, PartialEq)]
pub struct HostSection {
+ pub contrast: Option<ContrastOutcome>,
pub paint_alpha: Option<u8>,
pub section: SectionId,
pub instance: InstanceId,
@@ -765,6 +775,9 @@ impl HostLayout {
}
}
self.metrics.validate()?;
+ if self.geometry_policy.requested_opacity.is_some_and(|value| !value.is_finite() || !(0.0..=1.0).contains(&value)) {
+ return Err(error(Rule::Bounds, "invalid requested panel opacity"));
+ }
if self.geometry_policy.effective_surfaces.len() > MAX_SECTIONS {
return Err(error(Rule::CollectionLimit, "host geometry policy bound"));
}
@@ -1349,8 +1362,14 @@ fn append_section(
"ui.panel_host.resize",
);
}
- let paint_alpha = policy.surface_alpha.map(|alpha| if section.location.zone() == Zone::Floating { alpha.floating } else { alpha.docked });
+ let floating = section.location.zone() == Zone::Floating;
+ let appearance = policy.surfaces.as_ref().map(|style| style.appearance(surface, floating));
+ let paint_alpha = appearance
+ .map(|appearance| appearance.fill.a())
+ .or_else(|| policy.surface_alpha.map(|alpha| if floating { alpha.floating } else { alpha.docked }));
+ let contrast = appearance.map(|appearance| appearance.contrast.clone());
out.sections.push(HostSection {
+ contrast,
paint_alpha,
section: section.id.clone(),
instance: instance.clone(),
diff --git a/crates/ui-egui/src/panel_runtime/mod.rs b/crates/ui-egui/src/panel_runtime/mod.rs
index f4c1ddec6a..6a0aaef00d 100644
--- a/crates/ui-egui/src/panel_runtime/mod.rs
+++ b/crates/ui-egui/src/panel_runtime/mod.rs
@@ -8,6 +8,7 @@ mod layout;
mod preferences;
mod runtime;
mod specimen;
+mod surfaces;
mod workspace;
pub use app::*;
@@ -19,6 +20,7 @@ pub use preferences::*;
pub(crate) use preferences::{PanelLayoutSnapshot, panel_layout_matches, panel_layout_snapshot};
pub use runtime::*;
pub use specimen::*;
+pub use surfaces::*;
pub use workspace::*;
#[cfg(test)]
diff --git a/crates/ui-egui/src/panel_runtime/specimen.rs b/crates/ui-egui/src/panel_runtime/specimen.rs
index 3c3b9d4fb2..abbfac8019 100644
--- a/crates/ui-egui/src/panel_runtime/specimen.rs
+++ b/crates/ui-egui/src/panel_runtime/specimen.rs
@@ -13,7 +13,8 @@ use super::*;
const WORKSPACE: &str = "panel_fixture.workspace";
const INSPECT: &str = "panel_fixture.inspect";
-const PRESETS: &[&str] = &["docks", "tabs", "collapsed", "floating", "overflow", "pinned", "columns", "stack_tabs", "content_fill", "inline"];
+const PRESETS: &[&str] =
+ &["docks", "tabs", "collapsed", "floating", "overflow", "pinned", "columns", "stack_tabs", "content_fill", "inline", "surfaces"];
type SpecimenIdentities = Rc<RefCell<BTreeMap<ControllerKey, Rc<()>>>>;
fn preset(value: &str) -> PanelResult<()> {
@@ -23,10 +24,10 @@ fn preset(value: &str) -> PanelResult<()> {
/// The caller explicitly opts into original synthetic content at the actual
/// workspace composition point. An existing runtime is never replaced.
pub fn enable_host_specimen(app: &mut crate::SolveApp, name: &str) -> PanelResult<()> {
- enable_host_specimen_remembered(app, name, false)
+ enable_host_specimen_remembered(app, name, false, None)
}
-fn enable_host_specimen_remembered(app: &mut crate::SolveApp, name: &str, remember: bool) -> PanelResult<()> {
+fn enable_host_specimen_remembered(app: &mut crate::SolveApp, name: &str, remember: bool, requested_opacity: Option<f32>) -> PanelResult<()> {
preset(name)?;
if app.panel_runtime().is_some() {
return Err(error(Rule::Lifecycle, "panel specimen cannot take over an existing runtime"));
@@ -95,7 +96,10 @@ fn enable_host_specimen_remembered(app: &mut crate::SolveApp, name: &str, rememb
// the app or leaving a partially enabled specimen behind.
let mut integration = AppPanelRuntime::new(runtime, Box::new(services))?;
integration.tick(&app.session)?;
- integration.enable_host(HostOptions::default())?;
+ let mut options = HostOptions::default();
+ options.geometry.default_opaque = name != "surfaces";
+ integration.enable_host(options)?;
+ integration.set_requested_opacity(requested_opacity)?;
let repaired = if remember {
let mut catalogue = specimen_catalogue(name)?;
super::preferences::configure_preferences(&mut integration, &app.panel_layout_preferences, &mut catalogue)?
@@ -157,7 +161,13 @@ fn specimen_layout(name: &str) -> PanelResult<(Layout, PanelRegistry)> {
default_size: Size { width: 280.0, height: 240.0 },
max_size: Size { width: MAX_LOGICAL, height: 1200.0 },
edge_rule: if pinned { EdgeRule::PinOuter } else { EdgeRule::None },
- surface: PanelSurface::FollowZone,
+ surface: if name == "surfaces" && fill {
+ PanelSurface::Opaque
+ } else if name == "surfaces" && pinned {
+ PanelSurface::Translucent
+ } else {
+ PanelSurface::FollowZone
+ },
features: PanelFeatures { multi_instance: !editor, popout: false, hot_closable: editor, ..PanelFeatures::default() },
side_height_policy: if fill { SideHeightPolicy::Fill } else { SideHeightPolicy::Content },
header_actions: if editor {
@@ -169,7 +179,9 @@ fn specimen_layout(name: &str) -> PanelResult<(Layout, PanelRegistry)> {
})?;
}
let mut layout = Layout::empty(WorkspaceId::new(WORKSPACE)?);
- let count = if name == "overflow" {
+ let count = if name == "surfaces" {
+ 6
+ } else if name == "overflow" {
24
} else if name == "columns" {
3
@@ -184,16 +196,23 @@ fn specimen_layout(name: &str) -> PanelResult<(Layout, PanelRegistry)> {
let id = InstanceId::new(format!("specimen-{index}"))?;
let kind = if name == "inline" {
"fixture.log"
- } else if name == "content_fill" && index == 1 {
+ } else if (name == "content_fill" && index == 1) || (name == "surfaces" && index == 3) {
"fixture.fill"
- } else if name == "pinned" && index == 1 {
+ } else if (name == "pinned" && index == 1) || (name == "surfaces" && index == 2) {
"fixture.pin"
} else if index == 0 {
"fixture.editor"
} else {
"fixture.log"
};
- let zone = if name == "inline" {
+ let zone = if name == "surfaces" {
+ match index {
+ 0 | 1 => Zone::Left,
+ 2 | 3 => Zone::Right,
+ 4 => Zone::Bottom,
+ _ => Zone::Floating,
+ }
+ } else if name == "inline" {
Zone::Bottom
} else if matches!(name, "columns" | "stack_tabs") {
Zone::Left
@@ -206,12 +225,14 @@ fn specimen_layout(name: &str) -> PanelResult<(Layout, PanelRegistry)> {
_ => Zone::Bottom,
}
};
- let location = if name == "floating" {
+ let location = if name == "floating" || (name == "surfaces" && index == 5) {
SectionLocation::Floating { origin: Point { x: 48.0 + index as f32 * 64.0, y: 48.0 + index as f32 * 48.0 } }
} else {
SectionLocation::Dock { zone }
};
- let group = if name == "tabs" {
+ let group = if name == "surfaces" && index == 1 {
+ 0
+ } else if name == "tabs" {
index % 2
} else if name == "stack_tabs" && index == 3 {
1
@@ -233,6 +254,10 @@ fn specimen_layout(name: &str) -> PanelResult<(Layout, PanelRegistry)> {
let (location, column, collapsed, tab_index) = if let Some(section) = layout.sections.iter_mut().find(|section| section.id == section_id) {
let tab_index = section.tabs.len();
section.tabs.push(id.clone());
+ if name == "surfaces" {
+ // The inactive text-heavy editor still controls FollowZone.
+ section.active = id.clone();
+ }
(section.location.clone(), section.column.clone(), section.collapsed, tab_index)
} else {
if let Some(column) = &column
@@ -538,23 +563,42 @@ fn session_observation(app: &crate::SolveApp) -> Value {
/// An empty object inspects without ticking services or dispatching layout/model actions.
pub(crate) fn control_specimen(app: &mut crate::SolveApp, params: &Value) -> Result<Value, String> {
let object = params.as_object().ok_or("panel_fixture params must be an object")?;
- if object.keys().any(|key| !matches!(key.as_str(), "enabled" | "preset" | "remember")) {
+ if object.keys().any(|key| !matches!(key.as_str(), "enabled" | "preset" | "remember" | "translucency_percent")) {
return Err("unknown panel_fixture parameter".into());
}
let enabled = object.get("enabled").map(|v| v.as_bool().ok_or("enabled must be a boolean")).transpose()?;
let name = object.get("preset").map(|v| v.as_str().ok_or("preset must be a string")).transpose()?;
let remember = object.get("remember").map(|v| v.as_bool().ok_or("remember must be a boolean")).transpose()?;
+ let requested_opacity = object
+ .get("translucency_percent")
+ .map(|value| {
+ let percent = value
+ .as_f64()
+ .filter(|percent| percent.is_finite() && (0.0..=100.0).contains(percent))
+ .ok_or("translucency_percent must be a finite number from 0 to 100")?;
+ Ok::<f32, &str>((1.0 - percent / 100.0) as f32)
+ })
+ .transpose()?;
if let Some(name) = name {
preset(name).map_err(|e| e.to_string())?;
}
- if enabled == Some(false) && (name.is_some() || remember.is_some()) {
- return Err("preset or remember cannot be combined with enabled=false".into());
+ if enabled == Some(false) && (name.is_some() || remember.is_some() || requested_opacity.is_some()) {
+ return Err("preset, remember or translucency_percent cannot be combined with enabled=false".into());
}
if remember.is_some() && enabled != Some(true) && name.is_none() {
return Err("remember requires enabling a panel specimen".into());
}
if enabled == Some(true) || name.is_some() {
- enable_host_specimen_remembered(app, name.unwrap_or("docks"), remember.unwrap_or(false)).map_err(|e| e.to_string())?;
+ enable_host_specimen_remembered(app, name.unwrap_or("docks"), remember.unwrap_or(false), requested_opacity).map_err(|e| e.to_string())?;
+ } else if let Some(opacity) = requested_opacity {
+ if !app.universal_panel_host_enabled() || !app.panel_runtime().is_some_and(|runtime| specimen_workspace(&runtime.environment().workspace)) {
+ return Err("translucency_percent requires an enabled panel specimen host".into());
+ }
+ let integration = app.panel_runtime_mut().ok_or("panel specimen runtime disappeared")?;
+ // Confirm the provider as well as the workspace marker before changing
+ // an existing host. Updating presentation retains controllers and drafts.
+ integration.with_services(|_, services| services.models.read(&ContentOwner::Application, INSPECT)).map_err(|e| e.to_string())?;
+ integration.set_requested_opacity(Some(opacity)).map_err(|e| e.to_string())?;
}
let owns_runtime = app.panel_runtime().is_some_and(|runtime| specimen_workspace(&runtime.environment().workspace));
if enabled == Some(false) && app.panel_runtime().is_some() {
@@ -616,7 +660,7 @@ fn host_observation(app: &crate::SolveApp) -> Value {
json!({
"section":section.section,"instance":section.instance,"zone":section.zone,
"outer":section.outer,"header":section.header,"body":section.body,"footer":section.footer,
- "collapsed":section.collapsed,"inline":section.inline,"surface":section.surface,"paint_alpha":section.paint_alpha,"hidden_tabs":section.hidden_tabs,
+ "collapsed":section.collapsed,"inline":section.inline,"surface":section.surface,"paint_alpha":section.paint_alpha,"contrast":section.contrast,"hidden_tabs":section.hidden_tabs,
})
})
.collect();
diff --git a/crates/ui-egui/src/panel_runtime/surfaces.rs b/crates/ui-egui/src/panel_runtime/surfaces.rs
new file mode 100644
index 0000000000..e3911c3183
--- /dev/null
+++ b/crates/ui-egui/src/panel_runtime/surfaces.rs
@@ -0,0 +1,84 @@
+//! Captured, paint-only surface readability. Geometry and authored theme intent stay unchanged.
+use std::sync::Arc;
+
+use egui::Color32;
+use solidcraft_engine::panels::{ContrastFailure, ContrastOutcome, PanelSurface};
+
+use crate::theme::{self, Tokens};
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct HostSurfaceAppearance {
+ pub fill: Color32,
+ pub contrast: ContrastOutcome,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct HostSurfaceStyle {
+ authored: Arc<Tokens>,
+ fallback: Arc<Tokens>,
+ raw_fills: [Color32; 2],
+ force_opaque: bool,
+ requested_bits: Option<u32>,
+ dark: bool,
+ opaque: HostSurfaceAppearance,
+ docked: HostSurfaceAppearance,
+ floating: HostSurfaceAppearance,
+}
+
+impl HostSurfaceStyle {
+ /// `requested_opacity` is normalized opacity, not translucency or percent. None
+ /// retains the actual shared frame's effective theme/blur alpha.
+ pub fn capture(ctx: &egui::Context, force_opaque: bool, requested_opacity: Option<f32>, previous: Option<&Self>) -> Self {
+ let authored = Tokens::get();
+ let raw_fills = [crate::ui_kit::panel_host_frame(ctx, false).fill, crate::ui_kit::panel_host_frame(ctx, true).fill];
+ let requested_bits = requested_opacity.map(f32::to_bits);
+ let dark = theme::is_dark();
+ if let Some(previous) = previous.filter(|previous| {
+ *previous.authored == authored
+ && previous.raw_fills == raw_fills
+ && previous.force_opaque == force_opaque
+ && previous.requested_bits == requested_bits
+ && previous.dark == dark
+ }) {
+ return previous.clone();
+ }
+ let fallback = theme::panel_fallback_tokens(authored);
+ let invalid = requested_opacity.is_some_and(|alpha| !alpha.is_finite() || !(0.0..=1.0).contains(&alpha));
+ let resolve = |fill: Color32, opaque: bool| {
+ if invalid {
+ return fallback_appearance(&fallback, ContrastFailure::InvalidTokens);
+ }
+ let requested = if opaque || force_opaque { 1.0 } else { requested_opacity.unwrap_or(f32::from(fill.a()) / 255.0) };
+ resolve_appearance(fill, &authored, &fallback, requested)
+ };
+ let opaque = resolve(raw_fills[0], true);
+ let docked = resolve(raw_fills[0], false);
+ let floating = resolve(raw_fills[1], false);
+ Self { authored: Arc::new(authored), fallback: Arc::new(fallback), raw_fills, force_opaque, requested_bits, dark, opaque, docked, floating }
+ }
+
+ pub fn appearance(&self, surface: PanelSurface, floating: bool) -> &HostSurfaceAppearance {
+ if surface == PanelSurface::Opaque || self.force_opaque {
+ &self.opaque
+ } else if floating {
+ &self.floating
+ } else {
+ &self.docked
+ }
+ }
+
+ pub fn palette(&self, appearance: &HostSurfaceAppearance) -> &Tokens {
+ if matches!(appearance.contrast, ContrastOutcome::RetainReadableFallback { .. }) { &self.fallback } else { &self.authored }
+ }
+}
+
+fn fallback_appearance(tokens: &Tokens, reason: ContrastFailure) -> HostSurfaceAppearance {
+ HostSurfaceAppearance { fill: tokens.panel, contrast: ContrastOutcome::RetainReadableFallback { reason } }
+}
+
+fn resolve_appearance(fill: Color32, tokens: &Tokens, fallback: &Tokens, requested: f32) -> HostSurfaceAppearance {
+ match theme::panel_surface_fill(fill, tokens, requested) {
+ Some(fill) => HostSurfaceAppearance { fill, contrast: ContrastOutcome::Readable { effective_background_alpha: f32::from(fill.a()) / 255.0 } },
+ None => fallback_appearance(fallback, ContrastFailure::UnreadableAtFullOpacity),
+ }
+}
diff --git a/crates/ui-egui/src/panel_runtime/tests.rs b/crates/ui-egui/src/panel_runtime/tests.rs
index ecc3dfea99..8dab84033f 100644
--- a/crates/ui-egui/src/panel_runtime/tests.rs
+++ b/crates/ui-egui/src/panel_runtime/tests.rs
@@ -1,7 +1,285 @@
+#![cfg(test)]
+
use solidcraft_engine::panels::*;
use super::*;
+fn surface_test_palette(dark: bool) -> crate::theme::Tokens {
+ let mut tokens = if dark { crate::theme::Tokens::dark() } else { crate::theme::Tokens::light() };
+ tokens.panel = if dark { egui::Color32::BLACK } else { egui::Color32::WHITE };
+ let ink = if dark { egui::Color32::WHITE } else { egui::Color32::BLACK };
+ tokens.text = ink;
+ tokens.text_dim = ink;
+ tokens.form_ink = ink;
+ tokens.form_dim = ink;
+ tokens.dialog_label = ink;
+ tokens
+}
+
+#[test]
+fn panel_surface_policy_keeps_disabled_host_storage_small() {
+ assert!(
+ std::mem::size_of::<HostSurfaceStyle>() < std::mem::size_of::<crate::theme::Tokens>(),
+ "disabled host policy must not embed whole palettes in SolveApp"
+ );
+}
+
+#[test]
+fn panel_surface_contrast_covers_actual_light_dark_and_bundled_high_contrast() {
+ use egui::Color32;
+ use solidcraft_engine::geom::srgb::{decode8, encode8};
+ let high_contrast = crate::theme_files::resolve(crate::theme_files::find("high-contrast", &[]).unwrap());
+ // Independent stored-premultiplied source-over for both real renderer target
+ // formats. This does not call the production contrast/bounds predicate.
+ let blend = |source: Color32, ground: Color32, linear: bool| {
+ let remain = 1.0 - f64::from(source.a()) / 255.0;
+ let channel = |source: u8, ground: u8| {
+ if linear {
+ encode8(decode8(source) + decode8(ground) * remain)
+ } else {
+ (f64::from(source) + f64::from(ground) * remain).round().clamp(0.0, 255.0) as u8
+ }
+ };
+ Color32::from_rgb(channel(source.r(), ground.r()), channel(source.g(), ground.g()), channel(source.b(), ground.b()))
+ };
+ let inks = |tokens: &crate::theme::Tokens| [tokens.text, tokens.text_dim, tokens.form_ink, tokens.form_dim, tokens.dialog_label];
+ for (name, authored) in [("light", crate::theme::Tokens::light()), ("dark", crate::theme::Tokens::dark()), ("high-contrast", high_contrast)] {
+ let ctx = egui::Context::default();
+ let _scope = crate::theme::scoped_panel_tokens(authored);
+ assert!(inks(&authored).iter().all(|ink| ink.a() == 255), "these shipped canonical ink pairs are opaque: {name}");
+ for floating in [false, true] {
+ let raw = crate::ui_kit::panel_host_frame(&ctx, floating).fill.to_srgba_unmultiplied();
+ let opaque = Color32::from_rgb(raw[0], raw[1], raw[2]);
+ let impossible = inks(&authored).iter().any(|ink| crate::theme::contrast_ratio(*ink, opaque) < 4.5);
+ for translucency_percent in [0.0_f32, 50.0, 100.0] {
+ let requested = 1.0 - translucency_percent / 100.0;
+ let style = HostSurfaceStyle::capture(&ctx, false, Some(requested), None);
+ let appearance = style.appearance(PanelSurface::Translucent, floating);
+ let palette = style.palette(appearance);
+ match &appearance.contrast {
+ ContrastOutcome::Readable { effective_background_alpha } => {
+ assert!(!impossible, "a shipped unreadable authored pair cannot be reported compliant: {name}");
+ assert!(*effective_background_alpha >= requested);
+ assert_eq!(inks(palette), inks(&authored), "ordinary resolution preserves every canonical ink: {name}");
+ }
+ ContrastOutcome::RetainReadableFallback { reason } => {
+ assert!(impossible, "fallback is justified by an independently checked opaque pair: {name}");
+ assert_eq!(*reason, ContrastFailure::UnreadableAtFullOpacity);
+ assert_eq!(appearance.fill.a(), 255);
+ }
+ }
+ for viewport in [0, 1, 64, 117, 192, 254, 255] {
+ for linear in [false, true] {
+ let background = blend(appearance.fill, Color32::from_gray(viewport), linear);
+ for ink in inks(palette) {
+ let physical_ink = blend(ink, background, linear);
+ assert!(
+ crate::theme::contrast_ratio(physical_ink, background) >= 4.5,
+ "{name}: primary/muted text at translucency {translucency_percent}, viewport {viewport}, linear={linear}"
+ );
+ }
+ }
+ }
+ }
+ }
+ }
+}
+
+#[test]
+fn captured_panel_surfaces_protect_all_inks_at_requested_translucencies() {
+ let ctx = egui::Context::default();
+ for dark in [false, true] {
+ let tokens = surface_test_palette(dark);
+ let _scope = crate::theme::scoped_panel_tokens(tokens);
+ for translucency_percent in [0.0_f32, 50.0, 100.0] {
+ let opacity = 1.0 - translucency_percent / 100.0;
+ let style = HostSurfaceStyle::capture(&ctx, false, Some(opacity), None);
+ for floating in [false, true] {
+ let appearance = style.appearance(PanelSurface::Translucent, floating);
+ let ContrastOutcome::Readable { effective_background_alpha } = appearance.contrast else {
+ panic!("valid theme must remain authored")
+ };
+ assert!(effective_background_alpha >= opacity);
+ assert_eq!(effective_background_alpha, f32::from(appearance.fill.a()) / 255.0);
+ assert_eq!(style.palette(appearance), &tokens);
+ assert!(crate::theme::panel_surface_readable(appearance.fill, style.palette(appearance)));
+ if appearance.fill.a() > (opacity * 255.0).ceil() as u8 {
+ let [r, g, b, alpha] = appearance.fill.to_srgba_unmultiplied();
+ let previous = egui::Color32::from_rgba_unmultiplied(r, g, b, alpha - 1);
+ assert!(!crate::theme::panel_surface_readable(previous, &tokens), "chosen byte is the first readable candidate");
+ }
+ }
+ assert_eq!(style.appearance(PanelSurface::Opaque, false).fill.a(), 255);
+ }
+ }
+}
+
+#[test]
+fn panel_contrast_checks_interior_luminance_and_translucent_muted_inks() {
+ let mut tokens = surface_test_palette(false);
+ // This ink has >=4.5 contrast against both black and white, yet an interior
+ // viewport background can match it exactly. Endpoint checks alone are false.
+ let middle = egui::Color32::from_gray(117);
+ tokens.form_dim = middle;
+ assert!(crate::theme::contrast_ratio(middle, egui::Color32::BLACK) >= 4.5);
+ assert!(crate::theme::contrast_ratio(middle, egui::Color32::WHITE) >= 4.5);
+ assert!(!crate::theme::panel_surface_readable(egui::Color32::TRANSPARENT, &tokens));
+ tokens.form_dim = egui::Color32::from_rgba_unmultiplied(0, 0, 0, 240);
+ assert!(crate::theme::panel_surface_readable(egui::Color32::WHITE, &tokens), "RGBA ink is composited rather than rejected");
+ tokens.form_dim = egui::Color32::TRANSPARENT;
+ assert!(!crate::theme::panel_surface_readable(egui::Color32::WHITE, &tokens), "invisible muted ink cannot satisfy contrast");
+}
+
+#[test]
+fn panel_contrast_encloses_actual_premultiplied_gpu_blends() {
+ use egui::Color32;
+ use solidcraft_engine::geom::srgb::{decode8, encode8};
+ // Independent physical source-over oracle: read stored premultiplied bytes,
+ // never the production readability predicate or unpremultiplication helper.
+ let physical = |source: Color32, background: Color32, linear: bool, dither: f64| {
+ let remain = 1.0 - f64::from(source.a()) / 255.0;
+ let channel = |source: u8, background: u8| {
+ let source = f64::from(source) + dither;
+ if linear {
+ // Test source channels here are integer and undithered on the
+ // linear path; transfer-function fixtures independently cover it.
+ encode8(decode8(source.round().clamp(0.0, 255.0) as u8) + decode8(background) * remain)
+ } else {
+ (source + f64::from(background) * remain).round().clamp(0.0, 255.0) as u8
+ }
+ };
+ Color32::from_rgb(channel(source.r(), background.r()), channel(source.g(), background.g()), channel(source.b(), background.b()))
+ };
+ let premultiplied = Color32::from_rgba_premultiplied(32, 32, 32, 128);
+ let ground = Color32::from_gray(1);
+ assert_eq!(physical(premultiplied, ground, false, 0.0), Color32::from_gray(32));
+ assert_eq!(crate::theme::composite(premultiplied, ground), Color32::from_gray(33), "round-trip reconstruction is a different blend");
+ for background in [0, 1, 64, 117, 192, 254, 255] {
+ let ground = Color32::from_gray(background);
+ let (low, high) = crate::theme::panel_composite_bounds(premultiplied, ground);
+ for (linear, dither) in [(false, -0.475), (false, 0.0), (false, 0.475), (true, 0.0)] {
+ let actual = physical(premultiplied, ground, linear, dither);
+ assert!(low.r() <= actual.r() && actual.r() <= high.r(), "actual stored-byte blend lies inside conservative bounds");
+ }
+ }
+ let ctx = egui::Context::default();
+ for dark in [false, true] {
+ let mut tokens = surface_test_palette(dark);
+ tokens.form_dim = if dark { Color32::from_rgba_unmultiplied(255, 255, 255, 240) } else { Color32::from_rgba_unmultiplied(0, 0, 0, 240) };
+ let _scope = crate::theme::scoped_panel_tokens(tokens);
+ let style = HostSurfaceStyle::capture(&ctx, false, Some(0.0), None);
+ let appearance = style.appearance(PanelSurface::Translucent, false);
+ assert!(matches!(appearance.contrast, ContrastOutcome::Readable { .. }));
+ for viewport in [0, 1, 64, 117, 192, 254, 255] {
+ for linear in [false, true] {
+ let background = physical(appearance.fill, Color32::from_gray(viewport), linear, 0.0);
+ for ink in [tokens.text, tokens.text_dim, tokens.form_ink, tokens.form_dim, tokens.dialog_label] {
+ let text = physical(ink, background, linear, 0.0);
+ assert!(
+ crate::theme::contrast_ratio(text, background) >= 4.5,
+ "independent framebuffer blend preserves both primary and muted text"
+ );
+ }
+ }
+ }
+ }
+}
+
+#[test]
+fn panel_surface_cache_tracks_dark_mode_even_with_identical_authored_tokens() {
+ struct RestoreDark(bool);
+ impl Drop for RestoreDark {
+ fn drop(&mut self) {
+ crate::theme::set_dark(self.0);
+ }
+ }
+ let _restore = RestoreDark(crate::theme::is_dark());
+ let ctx = egui::Context::default();
+ let mut tokens = surface_test_palette(false);
+ tokens.form_dim = tokens.panel;
+ let _scope = crate::theme::scoped_panel_tokens(tokens);
+ crate::theme::set_dark(false);
+ let light = HostSurfaceStyle::capture(&ctx, false, Some(0.5), None);
+ crate::theme::set_dark(true);
+ let dark = HostSurfaceStyle::capture(&ctx, false, Some(0.5), Some(&light));
+ let light_appearance = light.appearance(PanelSurface::Translucent, false);
+ let dark_appearance = dark.appearance(PanelSurface::Translucent, false);
+ assert_ne!(light_appearance.fill, dark_appearance.fill, "fallback family changes despite identical captured authored tokens");
+ assert_eq!(HostSurfaceStyle::capture(&ctx, false, Some(0.5), Some(&dark)), dark);
+}
+
+#[test]
+fn invalid_panel_theme_reports_failure_and_uses_opaque_known_tokens() {
+ let ctx = egui::Context::default();
+ let mut tokens = surface_test_palette(false);
+ tokens.form_dim = tokens.panel;
+ tokens.space_4 = 7.0;
+ let _scope = crate::theme::scoped_panel_tokens(tokens);
+ for override_alpha in [Some(0.5), Some(f32::NAN), Some(f32::INFINITY), Some(-0.1), Some(1.1)] {
+ let style = HostSurfaceStyle::capture(&ctx, false, override_alpha, None);
+ let appearance = style.appearance(PanelSurface::Translucent, false);
+ let expected = if override_alpha.is_some_and(|a| !a.is_finite() || !(0.0..=1.0).contains(&a)) {
+ ContrastFailure::InvalidTokens
+ } else {
+ ContrastFailure::UnreadableAtFullOpacity
+ };
+ assert_eq!(appearance.contrast, ContrastOutcome::RetainReadableFallback { reason: expected });
+ assert_eq!(appearance.fill.a(), 255);
+ assert!(crate::theme::panel_surface_readable(appearance.fill, style.palette(appearance)));
+ assert_eq!(style.palette(appearance).space_4, tokens.space_4, "fallback does not change layout metrics");
+ let cached = HostSurfaceStyle::capture(&ctx, false, override_alpha, Some(&style));
+ assert_eq!(cached, style, "even an invalid raw NaN override has a stable bitwise cache key");
+ }
+}
+
+#[test]
+fn panel_surface_capture_matches_shared_frames_and_respects_accessibility() {
+ let ctx = egui::Context::default();
+ let tokens = surface_test_palette(false);
+ let _scope = crate::theme::scoped_panel_tokens(tokens);
+ let style = HostSurfaceStyle::capture(&ctx, false, None, None);
+ for floating in [false, true] {
+ let requested = crate::ui_kit::panel_host_frame(&ctx, floating).fill;
+ assert!(style.appearance(PanelSurface::Translucent, floating).fill.a() >= requested.a());
+ }
+ assert_eq!(HostSurfaceStyle::capture(&ctx, false, None, Some(&style)), style);
+ let forced = HostSurfaceStyle::capture(&ctx, true, Some(0.0), Some(&style));
+ assert_ne!(forced, style);
+ for floating in [false, true] {
+ let appearance = forced.appearance(PanelSurface::Translucent, floating);
+ assert_eq!(appearance.fill.a(), 255);
+ assert!(crate::theme::panel_surface_readable(appearance.fill, forced.palette(appearance)));
+ }
+ let second_context = egui::Context::default();
+ assert_eq!(HostSurfaceStyle::capture(&second_context, false, None, Some(&style)), style);
+ let mut changed = tokens;
+ changed.text_dim = egui::Color32::from_gray(20);
+ let _changed = crate::theme::scoped_panel_tokens(changed);
+ assert_ne!(HostSurfaceStyle::capture(&ctx, false, None, Some(&style)), style);
+}
+
+#[test]
+fn panel_paint_palette_scope_restores_nested_tokens_without_changing_base_theme() {
+ let before = crate::theme::Tokens::get();
+ let base = crate::theme::Tokens::base();
+ let mut outer = before;
+ outer.text = outer.file_primary_ink;
+ {
+ let _outer = crate::theme::scoped_panel_tokens(outer);
+ assert_eq!(crate::theme::Tokens::get(), outer);
+ assert_eq!(crate::theme::Tokens::get_in(crate::theme::ColorVision::Off), outer);
+ assert_eq!(crate::theme::Tokens::base(), base);
+ {
+ let inner = surface_test_palette(false);
+ let _inner = crate::theme::scoped_panel_tokens(inner);
+ assert_eq!(crate::theme::Tokens::get(), inner);
+ }
+ assert_eq!(crate::theme::Tokens::get(), outer);
+ }
+ assert_eq!(crate::theme::Tokens::get(), before);
+ assert_eq!(crate::theme::Tokens::base(), base);
+}
+
fn prepare_preference_fixture(app: &mut crate::SolveApp) {
app.panel_runtime
.as_mut()
@@ -12111,12 +12389,18 @@ fn captured_renderer_alpha_reaches_new_sections_and_alpha_only_drift_invalidates
h.app.ui.layout = mode;
h.frames(2);
let painted = h.app.universal_panel_frame().unwrap().layout.clone();
+ let captured_style = painted.geometry_policy.surfaces.as_ref().unwrap();
let alpha = HostSurfaceAlpha {
- docked: crate::ui_kit::panel_host_frame(&h.ctx, false).fill.a(),
- floating: crate::ui_kit::panel_host_frame(&h.ctx, true).fill.a(),
+ docked: captured_style.appearance(PanelSurface::FollowZone, false).fill.a(),
+ floating: captured_style.appearance(PanelSurface::FollowZone, true).fill.a(),
};
assert_eq!(painted.geometry_policy.surface_alpha, Some(alpha), "the actual app captures the shared renderer policy before allocation");
- assert!(painted.sections.iter().all(|card| card.paint_alpha == Some(alpha.docked)));
+ for card in &painted.sections {
+ let appearance = captured_style.appearance(card.surface, card.peek || card.zone == Zone::Floating);
+ assert_eq!(card.paint_alpha, Some(appearance.fill.a()));
+ assert_eq!(card.contrast.as_ref(), Some(&appearance.contrast));
+ assert_eq!(card.paint_alpha, Some(255), "Classic's default opaque policy is preserved");
+ }
let gap = crate::ui_kit::Container::for_layout(mode, crate::ui_kit::Surface::Panel).gap();
assert_eq!(gap, if mode == crate::shell::LayoutMode::Floating { 7.0 } else { 0.0 });
assert_eq!(painted.metrics.gap, gap);
@@ -12159,6 +12443,17 @@ fn captured_renderer_alpha_reaches_new_sections_and_alpha_only_drift_invalidates
.unwrap()
};
let reference = resolve(&policy);
+ let mut styled_policy = policy.clone();
+ styled_policy.default_opaque = false;
+ styled_policy.surfaces = Some(HostSurfaceStyle::capture(&h.ctx, false, Some(0.5), None));
+ let styled = resolve(&styled_policy);
+ for card in &styled.sections {
+ let appearance = styled_policy.surfaces.as_ref().unwrap().appearance(card.surface, card.peek || card.zone == Zone::Floating);
+ assert_eq!(card.paint_alpha, Some(appearance.fill.a()));
+ assert_eq!(card.contrast.as_ref(), Some(&appearance.contrast));
+ }
+ assert_eq!(styled.render_domain, reference.render_domain);
+ assert_eq!(styled.controls, reference.controls, "appearance leaves all pointer bounds and identities intact");
let action = transaction(vec![
fixture_open("fixture.log", "alpha-dock", "alpha-dock", Zone::Right, 1).unwrap(),
Mutation::Open {
diff --git a/crates/ui-egui/src/panel_runtime/workspace.rs b/crates/ui-egui/src/panel_runtime/workspace.rs
index 011eeecb31..5dd4f411dd 100644
--- a/crates/ui-egui/src/panel_runtime/workspace.rs
+++ b/crates/ui-egui/src/panel_runtime/workspace.rs
@@ -243,7 +243,26 @@ pub struct WorkspacePanelHost {
last_chrome: Vec<LogicalRect>,
}
+fn validate_requested_opacity(opacity: Option<f32>) -> PanelResult<()> {
+ if opacity.is_some_and(|value| !value.is_finite() || !(0.0..=1.0).contains(&value)) {
+ return Err(error(Rule::Bounds, "invalid requested panel opacity"));
+ }
+ Ok(())
+}
+
impl WorkspacePanelHost {
+ /// Override host paint opacity for this runtime only, without changing saved layout.
+ pub fn set_requested_opacity(&mut self, opacity: Option<f32>) -> PanelResult<()> {
+ validate_requested_opacity(opacity)?;
+ if self.options.geometry.requested_opacity != opacity {
+ self.invalidate_geometry();
+ self.options.geometry.requested_opacity = opacity;
+ self.options.geometry.surfaces = None;
+ self.options.geometry.surface_alpha = None;
+ }
+ Ok(())
+ }
+
pub(crate) fn set_gap(&mut self, gap: f32) -> PanelResult<()> {
let metrics = HostMetrics { gap, ..self.options.metrics };
metrics.validate()?;
@@ -265,12 +284,7 @@ impl WorkspacePanelHost {
for section in options.geometry.effective_surfaces.keys() {
valid_id(&section.0)?;
}
- // Declarative transparency/contrast policy belongs to the surface peer.
- // Appearance follows the existing adaptive Container, including its fill
- // alpha; this guard does not force an opaque paint override.
- if !options.geometry.default_opaque || options.geometry.effective_surfaces.values().any(|surface| *surface == PanelSurface::Translucent) {
- return Err(error(Rule::Capability, "translucent host requires the surface renderer"));
- }
+ validate_requested_opacity(options.geometry.requested_opacity)?;
Ok(Self {
options,
native_capabilities: HostCapabilities::default(),
@@ -461,12 +475,16 @@ impl WorkspacePanelHost {
self.prepare_in_domain(runtime, capacity, capacity, &[])
}
- pub(crate) fn note_egui_context(&mut self, ctx: &egui::Context) {
+ pub(crate) fn note_egui_context(&mut self, ctx: &egui::Context, force_opaque: bool) {
self.egui_context = Some(ctx.clone());
- let surface_alpha =
- Some(HostSurfaceAlpha { docked: ui_kit::panel_host_frame(ctx, false).fill.a(), floating: ui_kit::panel_host_frame(ctx, true).fill.a() });
- if self.options.geometry.surface_alpha != surface_alpha {
+ let surfaces = HostSurfaceStyle::capture(ctx, force_opaque, self.options.geometry.requested_opacity, self.options.geometry.surfaces.as_ref());
+ let surface_alpha = Some(HostSurfaceAlpha {
+ docked: surfaces.appearance(PanelSurface::FollowZone, false).fill.a(),
+ floating: surfaces.appearance(PanelSurface::FollowZone, true).fill.a(),
+ });
+ if self.options.geometry.surfaces.as_ref() != Some(&surfaces) || self.options.geometry.surface_alpha != surface_alpha {
self.invalidate_geometry();
+ self.options.geometry.surfaces = Some(surfaces);
self.options.geometry.surface_alpha = surface_alpha;
}
}
@@ -1845,11 +1863,21 @@ impl PanelHost for WorkspaceContentHost<'_> {
let surface_target = HostControlTarget::Pointer(HostPointerTarget::Surface { instance: geometry.instance.clone() });
let surface_id = scoped_id(self.scope, self.window, Some(&context.owner), &surface_target);
let mut failure = None;
+ let fallback;
+ let style = if let Some(style) = self.layout.geometry_policy.surfaces.as_ref() {
+ style
+ } else {
+ fallback = HostSurfaceStyle::capture(self.ui.ctx(), false, self.layout.geometry_policy.requested_opacity, None);
+ &fallback
+ };
+ let appearance = style.appearance(section.surface, section.peek || section.zone == Zone::Floating);
ui_kit::panel_host_surface(
self.ui,
section_surface_id(self.scope, self.window, &section.section),
egui_rect(section.outer),
section.peek || section.zone == Zone::Floating,
+ appearance.fill,
+ matches!(appearance.contrast, ContrastOutcome::RetainReadableFallback { .. }).then(|| style.palette(appearance)),
|ui, content_clip| {
if (section.peek || section.zone == Zone::Floating) && (!ui.is_visible() || ui.is_sizing_pass()) {
self.unpainted.push((ui.layer_id(), section.outer));
diff --git a/crates/ui-egui/src/prefs.rs b/crates/ui-egui/src/prefs.rs
index cf8b8ad916..132c60f2fa 100644
--- a/crates/ui-egui/src/prefs.rs
+++ b/crates/ui-egui/src/prefs.rs
@@ -3575,7 +3575,7 @@ pub(crate) fn blur_availability(app: &SolveApp) -> crate::theme_options::Availab
fn blur_availability_for(app: &SolveApp, offered: bool) -> crate::theme_options::Availability {
use crate::theme_options::Availability::{Available, Unavailable};
- let reduced = app.services.reduce_transparency.as_ref().and_then(|read| read(offered));
+ let reduced = app.services.reduce_transparency.as_ref().and_then(|read| read(offered || app.universal_panel_host_enabled()));
if !offered && app.blur_session.harness_radius.is_none() {
return Available;
}
@@ -3615,7 +3615,7 @@ pub(crate) fn prepare_blur(app: &mut SolveApp, ctx: &egui::Context) {
blur_availability_for(app, intent.offered)
} else {
if let Some(read) = &app.services.reduce_transparency {
- read(intent.offered);
+ read(intent.offered || app.universal_panel_host_enabled());
}
crate::theme_options::Availability::Available
};
diff --git a/crates/ui-egui/src/shell_tests.rs b/crates/ui-egui/src/shell_tests.rs
index c05c8739ec..d51eb1e442 100644
--- a/crates/ui-egui/src/shell_tests.rs
+++ b/crates/ui-egui/src/shell_tests.rs
@@ -48,7 +48,7 @@ fn assert_panel_host_preserves_design(h: &mut Harness, exercise: impl FnOnce(&mu
#[test]
fn universal_panel_host_is_opt_in_and_each_specimen_preserves_design_and_preferences() {
- for preset in ["docks", "tabs", "collapsed", "floating", "overflow", "pinned"] {
+ for preset in ["docks", "tabs", "collapsed", "floating", "overflow", "pinned", "surfaces"] {
let mut h = Harness::new();
h.app.home.open = false;
h.app.run("solid.box", json!({"length":40,"width":30,"height":20})).unwrap();
@@ -76,6 +76,45 @@ fn universal_panel_host_is_opt_in_and_each_specimen_preserves_design_and_prefere
}
}
+#[test]
+fn surface_fixture_routes_real_input_through_short_panel_gaps_at_both_scales_and_directions() {
+ use crate::panel_runtime::egui_rect;
+ use solidcraft_engine::panels::{PanelSurface, Point, Zone};
+ for scale in [1.0, 2.0] {
+ for language in ["en", "ar"] {
+ let mut h = Harness::new();
+ h.app.home.open = false;
+ h.app.preferences.language = language.into();
+ h.call("ui.resize", json!({"width":1600,"height":1100}));
+ h.app.run("solid.box", json!({"length":40,"width":30,"height":20})).unwrap();
+ h.settle();
+ h.ctx.set_pixels_per_point(scale);
+ crate::panel_runtime::control_specimen(&mut h.app, &json!({"preset":"surfaces","translucency_percent":100})).unwrap();
+ h.frames(5);
+ let frame = h.app.universal_panel_frame().unwrap();
+ assert_eq!(frame.layout.render_domain, crate::panel_runtime::logical_rect(h.app.viewport.rect.unwrap()));
+ let left = frame.layout.sections.iter().find(|section| section.zone == Zone::Left).unwrap();
+ assert_eq!(left.surface, PanelSurface::Opaque, "the inactive text-heavy editor constrains its tab group");
+ let clear = frame.layout.sections.iter().find(|section| section.instance.0 == "specimen-2").unwrap();
+ assert_eq!(clear.surface, PanelSurface::Translucent);
+ assert!(clear.contrast.is_some(), "effective alpha must have a truthful diagnostic");
+ let body = egui_rect(clear.body.unwrap());
+ let blocked = body.center();
+ let gap = egui::pos2(left.outer.origin.x + left.outer.size.width * 0.5, left.outer.origin.y + left.outer.size.height + 24.0);
+ assert!(!frame.layout.consumes_pointer(Point { x: gap.x, y: gap.y }), "short side content leaves a real gap");
+ let camera = h.app.cam;
+ h.call("ui.move", json!({"x":blocked.x,"y":blocked.y}));
+ h.call("ui.scroll", json!({"x":blocked.x,"y":blocked.y,"delta":120}));
+ assert!(h.app.viewport.mouse.is_none(), "translucent content shields model picking");
+ assert_eq!(h.app.cam, camera, "content wheel cannot reach model navigation");
+ h.call("ui.move", json!({"x":gap.x,"y":gap.y}));
+ assert_eq!(h.app.viewport.mouse, Some(gap), "uncovered points reach the existing picking path");
+ h.call("ui.scroll", json!({"x":gap.x,"y":gap.y,"delta":120}));
+ assert_ne!(h.app.cam.distance.to_bits(), camera.distance.to_bits(), "gap wheel reaches the existing navigation path");
+ }
+ }
+}
+
#[test]
fn specimen_rejects_unknown_presets_and_cannot_take_over_an_existing_runtime() {
let mut h = Harness::new();
diff --git a/crates/ui-egui/src/theme.rs b/crates/ui-egui/src/theme.rs
index da074b27fc..b9547ecd65 100644
--- a/crates/ui-egui/src/theme.rs
+++ b/crates/ui-egui/src/theme.rs
@@ -30,6 +30,8 @@ thread_local! {
/// The palette of a theme file (`theme_files`) in place of the built-in one of its base
/// (dark or light), per thread like the rest. `None`: the built-in palettes.
static CUSTOM: Cell<Option<Custom>> = const { Cell::new(None) };
+ /// Paint-only panel palette. It never changes authored theme state or cache generations.
+ static PANEL_TOKENS: Cell<Option<Tokens>> = const { Cell::new(None) };
static CUSTOM_GENERATION: Cell<u64> = const { Cell::new(0) };
/// The application bar's logo in the theme's accent instead of its own logo colours
/// (Preferences › Interface › Logo), per thread like the rest.
@@ -577,6 +579,21 @@ pub(crate) fn scoped_tokens(tokens: Tokens) -> impl Drop {
restore
}
+/// Temporarily bind a panel's paint palette without publishing a theme change.
+pub(crate) fn scoped_panel_tokens(tokens: Tokens) -> impl Drop {
+ struct Restore {
+ previous: Option<Tokens>,
+ // The override belongs to this UI thread, so its guard must not move to another one.
+ _thread: std::marker::PhantomData<std::rc::Rc<()>>,
+ }
+ impl Drop for Restore {
+ fn drop(&mut self) {
+ PANEL_TOKENS.set(self.previous);
+ }
+ }
+ Restore { previous: PANEL_TOKENS.replace(Some(tokens)), _thread: std::marker::PhantomData }
+}
+
/// A tab's selection colours. This is deliberately separate from the global widget style:
/// application chrome, checkboxes, status colours and dialog actions retain their own tokens.
#[derive(Clone, Copy, Debug, PartialEq)]
@@ -615,6 +632,93 @@ pub(crate) fn composite(fill: Color32, background: Color32) -> Color32 {
Color32::from_rgb(channel(0), channel(1), channel(2))
}
+pub(crate) fn panel_fallback_tokens(mut authored: Tokens) -> Tokens {
+ // Bypass custom/published themes. These existing built-in pairs have their own
+ // contrast tests. Copy only surface/ink roles to retain captured layout metrics.
+ let known = if is_dark() { Tokens::dark() } else { Tokens::light() };
+ authored.panel = known.file_background.to_opaque();
+ authored.panel_header = authored.panel;
+ authored.text = known.file_primary_ink;
+ authored.form_ink = known.file_primary_ink;
+ authored.dialog_label = known.file_primary_ink;
+ authored.text_dim = known.file_dim;
+ authored.form_dim = known.file_dim;
+ authored
+}
+
+/// Raise a captured panel fill to the first quantized alpha that protects all
+/// canonical inks. None reports an authored pair that fails at full opacity.
+pub(crate) fn panel_surface_fill(fill: Color32, tokens: &Tokens, requested: f32) -> Option<Color32> {
+ let [r, g, b, _] = fill.to_srgba_unmultiplied();
+ if !requested.is_finite() || !(0.0..=1.0).contains(&requested) || !panel_surface_readable(Color32::from_rgb(r, g, b), tokens) {
+ return None;
+ }
+ // Each candidate is the renderer's exact quantized fill. Round upward so
+ // effective alpha never undercuts the caller's requested opacity.
+ for alpha in (requested * 255.0).ceil() as u8..=255 {
+ let candidate = Color32::from_rgba_unmultiplied(r, g, b, alpha);
+ if panel_surface_readable(candidate, tokens) {
+ return Some(candidate);
+ }
+ }
+ None
+}
+
+fn panel_luminance(color: Color32) -> f64 {
+ let decode = solidcraft_engine::geom::srgb::decode8;
+ 0.2126 * decode(color.r()) + 0.7152 * decode(color.g()) + 0.0722 * decode(color.b())
+}
+
+pub(crate) fn panel_surface_readable(fill: Color32, tokens: &Tokens) -> bool {
+ let (low, _) = panel_composite_bounds(fill, Color32::BLACK);
+ let (_, high) = panel_composite_bounds(fill, Color32::WHITE);
+ let (background_low, background_high) = (panel_luminance(low), panel_luminance(high));
+ [tokens.text, tokens.text_dim, tokens.form_ink, tokens.form_dim, tokens.dialog_label].into_iter().all(|ink| {
+ // RGBA inks remain authored. Conservative intervals include every possible
+ // composited text luminance, including an interior contrast minimum.
+ let ink_low = panel_luminance(panel_composite_bounds(ink, low).0);
+ let ink_high = panel_luminance(panel_composite_bounds(ink, high).1);
+ if ink_low <= background_high && ink_high >= background_low {
+ false
+ } else if ink_low > background_high {
+ (ink_low + 0.05) / (background_high + 0.05) >= 4.5
+ } else {
+ (background_low + 0.05) / (ink_high + 0.05) >= 4.5
+ }
+ })
+}
+
+/// Enclose the actual stored-premultiplied source-over, without unpremultiplying
+/// and rounding the source again. egui-wgpu's renderer uses One/OneMinusSrcAlpha;
+/// its two WGSL entry points blend gamma codes or decoded premultiplied codes.
+/// Include both framebuffer formats and the shader's <half-byte source dither,
+/// then round outward to cover framebuffer quantization. This intentionally
+/// overestimates uncertainty instead of promising threshold contrast falsely.
+pub(crate) fn panel_composite_bounds(source: Color32, background: Color32) -> (Color32, Color32) {
+ use solidcraft_engine::geom::srgb::{decode, encode};
+ if source.a() == 255 {
+ // Flat opaque integer colours survive the shader's <0.5-byte dither and
+ // final nearest-byte conversion unchanged on either framebuffer format.
+ return (source, source);
+ }
+ let remain = 1.0 - f64::from(source.a()) / 255.0;
+ let channel = |source: u8, background: u8| {
+ let source = f64::from(source);
+ let background = f64::from(background);
+ let low_source = (source - 0.5).max(0.0);
+ let high_source = (source + 0.5).min(255.0);
+ let gamma_low = low_source + background * remain;
+ let gamma_high = high_source + background * remain;
+ let linear_low = encode(decode(low_source / 255.0) + decode(background / 255.0) * remain) * 255.0;
+ let linear_high = encode(decode(high_source / 255.0) + decode(background / 255.0) * remain) * 255.0;
+ (gamma_low.min(linear_low).floor().clamp(0.0, 255.0) as u8, gamma_high.max(linear_high).ceil().clamp(0.0, 255.0) as u8)
+ };
+ let (r0, r1) = channel(source.r(), background.r());
+ let (g0, g1) = channel(source.g(), background.g());
+ let (b0, b1) = channel(source.b(), background.b());
+ (Color32::from_rgb(r0, g0, b0), Color32::from_rgb(r1, g1, b1))
+}
+
fn readable_fill(fill: Color32, inks: &[Color32], scale: f32) -> Color32 {
let readable = |candidate| {
[Color32::BLACK, Color32::WHITE].iter().all(|background| {
@@ -1328,6 +1432,9 @@ impl Tokens {
/// [`Tokens::get`] in another colour vision mode: the Colour vision preference previews the
/// mode being chosen before it is applied (#7152).
pub fn get_in(mode: ColorVision) -> Tokens {
+ if let Some(tokens) = PANEL_TOKENS.get() {
+ return tokens;
+ }
if let Some(published) = PUBLISHED.get().filter(|p| p.environment == Environment::current()) {
if mode == published.environment.vision {
return published.tokens;
diff --git a/crates/ui-egui/src/ui_kit/panel_host.rs b/crates/ui-egui/src/ui_kit/panel_host.rs
index a65790e4c8..82b304c0fc 100644
--- a/crates/ui-egui/src/ui_kit/panel_host.rs
+++ b/crates/ui-egui/src/ui_kit/panel_host.rs
@@ -31,10 +31,14 @@ pub(crate) fn panel_host_surface<R>(
id: egui::Id,
bounds: egui::Rect,
floating: bool,
+ fill: egui::Color32,
+ palette: Option<&Tokens>,
body: impl FnOnce(&mut egui::Ui, egui::Rect) -> R,
) -> R {
+ let _tokens = palette.map(|tokens| crate::theme::scoped_panel_tokens(*tokens));
let container = panel_host_container(ui.ctx(), floating);
- let frame = panel_host_frame(ui.ctx(), floating);
+ let mut frame = panel_host_frame(ui.ctx(), floating);
+ frame.fill = fill;
let clip = ui.clip_rect().intersect(bounds);
// egui clips to rectangles. This inscribed rectangle keeps arbitrary content
// fills inside the rounded frame without changing any header hit target.
@@ -46,6 +50,15 @@ pub(crate) fn panel_host_surface<R>(
let mut child = ui.new_child(egui::UiBuilder::new().id_salt(id).max_rect(bounds));
child.set_clip_rect(clip);
container.paint_background(child.painter(), frame, bounds - frame.total_margin());
+ if let Some(tokens) = palette {
+ let visuals = child.visuals_mut();
+ visuals.override_text_color = Some(tokens.text);
+ visuals.weak_text_color = Some(tokens.form_dim);
+ visuals.widgets.noninteractive.fg_stroke.color = tokens.text;
+ for state in [&mut visuals.widgets.inactive, &mut visuals.widgets.hovered, &mut visuals.widgets.active, &mut visuals.widgets.open] {
+ state.fg_stroke.color = tokens.form_ink;
+ }
+ }
let result = body(&mut child, content_clip);
Container::paint_inset_clipped(child.painter(), bounds, frame, clip);
result
diff --git a/crates/ui-egui/src/ui_kit/panel_tests.rs b/crates/ui-egui/src/ui_kit/panel_tests.rs
index 1507bfcbb4..5d9267844c 100644
--- a/crates/ui-egui/src/ui_kit/panel_tests.rs
+++ b/crates/ui-egui/src/ui_kit/panel_tests.rs
@@ -457,35 +457,43 @@ fn universal_kit_chrome_uses_one_container_and_preserves_parent_clipping_and_foc
let mut calls = 0;
let output = crate::test_support::frame(&ctx, egui::RawInput::default(), |ui| {
ui.set_clip_rect(clip);
- panel_host_surface(ui, egui::Id::unique("synthetic-section"), bounds, false, |ui, content_clip| {
- calls += 1;
- assert_eq!(ui.clip_rect(), clip);
- assert!(clip.contains_rect(content_clip));
- let outer_frames = ui.stack().iter().filter(|node| node.frame().fill != egui::Color32::TRANSPARENT).count();
- assert!(outer_frames <= 1, "a section must not introduce nested outer frames");
- let title = panel_host_control(
- ui,
- egui::Id::unique("synthetic-header"),
- header,
- HostChrome {
- label: "Synthetic long localized panel title",
- icon: Some("list"),
- icon_only: false,
- attention: true,
- selected: false,
- enabled: true,
- drag: true,
- title: true,
- grip_only: false,
- rtl: false,
- },
- );
- let resize = panel_host_sash(ui, egui::Id::unique("synthetic-sash"), sash, "Resize synthetic neighbours");
- assert!(title.sense.is_focusable());
- assert!(resize.sense.is_focusable());
- assert_eq!(title.rect, header);
- assert_eq!(resize.rect, sash);
- });
+ panel_host_surface(
+ ui,
+ egui::Id::unique("synthetic-section"),
+ bounds,
+ false,
+ panel_host_frame(ui.ctx(), false).fill,
+ None,
+ |ui, content_clip| {
+ calls += 1;
+ assert_eq!(ui.clip_rect(), clip);
+ assert!(clip.contains_rect(content_clip));
+ let outer_frames = ui.stack().iter().filter(|node| node.frame().fill != egui::Color32::TRANSPARENT).count();
+ assert!(outer_frames <= 1, "a section must not introduce nested outer frames");
+ let title = panel_host_control(
+ ui,
+ egui::Id::unique("synthetic-header"),
+ header,
+ HostChrome {
+ label: "Synthetic long localized panel title",
+ icon: Some("list"),
+ icon_only: false,
+ attention: true,
+ selected: false,
+ enabled: true,
+ drag: true,
+ title: true,
+ grip_only: false,
+ rtl: false,
+ },
+ );
+ let resize = panel_host_sash(ui, egui::Id::unique("synthetic-sash"), sash, "Resize synthetic neighbours");
+ assert!(title.sense.is_focusable());
+ assert!(resize.sense.is_focusable());
+ assert_eq!(title.rect, header);
+ assert_eq!(resize.rect, sash);
+ },
+ );
});
assert!(calls >= 1);
let tree = output.platform_output.accesskit_update.as_ref().unwrap();
@@ -528,12 +536,12 @@ fn universal_surface_uses_adaptive_workspace_fill_and_rounding_with_safe_content
if free_card {
// A new floating Area first measures invisibly, even with fade disabled.
crate::test_support::frame(&ctx, egui::RawInput { time: Some(0.0), ..Default::default() }, |ui| {
- panel_host_surface(ui, egui::Id::unique("adaptive-surface"), bounds, free_card, |_, _| {});
+ panel_host_surface(ui, egui::Id::unique("adaptive-surface"), bounds, free_card, expected.fill, None, |_, _| {});
});
}
for time in [1.0, 2.0] {
let output = crate::test_support::frame(&ctx, egui::RawInput { time: Some(time), ..Default::default() }, |ui| {
- panel_host_surface(ui, egui::Id::unique("adaptive-surface"), bounds, free_card, |ui, clip| {
+ panel_host_surface(ui, egui::Id::unique("adaptive-surface"), bounds, free_card, expected.fill, None, |ui, clip| {
assert!(ui.is_visible() && !ui.is_sizing_pass(), "assert the first visible paint and its subsequent frame");
assert!(bounds.contains_rect(clip));
let stroke = expected.stroke.width;
@@ -2596,3 +2604,91 @@ fn page_sidebar_footer_stays_visible_when_the_page_list_scrolls() {
assert!(nav.contains_rect(scenario::rect_of("prefs:page:Plugins").unwrap()), "last page is reachable in {theme}");
}
}
+
+#[test]
+fn host_surface_fallback_paints_readable_plain_labels_without_changing_body_layout() {
+ use solidcraft_engine::panels::{ContrastOutcome, PanelSurface};
+ let bounds = egui::Rect::from_min_size(egui::pos2(40.0, 40.0), egui::vec2(320.0, 180.0));
+ for floating in [false, true] {
+ for fallback in [false, true] {
+ let ctx = crate::fonts::test_context();
+ let mut authored = Tokens::get();
+ authored.panel = egui::Color32::WHITE;
+ authored.text = egui::Color32::BLACK;
+ authored.text_dim = egui::Color32::BLACK;
+ authored.form_ink = egui::Color32::BLACK;
+ authored.form_dim = egui::Color32::BLACK;
+ authored.dialog_label = egui::Color32::BLACK;
+ if fallback {
+ authored.text = authored.panel;
+ }
+ let _authored = crate::theme::scoped_panel_tokens(authored);
+ let style = crate::panel_runtime::HostSurfaceStyle::capture(&ctx, false, Some(0.0), None);
+ let appearance = style.appearance(PanelSurface::Translucent, floating);
+ let failed = matches!(appearance.contrast, ContrastOutcome::RetainReadableFallback { .. });
+ assert_eq!(failed, fallback, "exercise both authored paint and deliberately unreadable fallback");
+ let palette = failed.then(|| style.palette(appearance));
+ let font = egui::FontId::monospace(19.0);
+ // Floating Areas create a fresh Ui from the context style; they do
+ // not inherit a caller's local Ui overrides. Set the common baseline
+ // before the sizing pass so both existing host paths inherit it.
+ ctx.global_style_mut(|style| {
+ style.override_font_id = Some(font.clone());
+ style.spacing.item_spacing = egui::vec2(13.0, 17.0);
+ style.wrap_mode = Some(egui::TextWrapMode::Wrap);
+ style.visuals.override_text_color = Some(authored.panel);
+ });
+ if floating {
+ crate::test_support::frame(&ctx, egui::RawInput::default(), |ui| {
+ panel_host_surface(ui, egui::Id::unique("captured-fill"), bounds, floating, appearance.fill, palette, |_, _| {});
+ });
+ }
+ let mut expected_ink = egui::Color32::TRANSPARENT;
+ let output = crate::test_support::frame(&ctx, egui::RawInput::default(), |ui| {
+ let parent_visuals = ui.visuals().clone();
+ let parent_spacing = ui.spacing().item_spacing;
+ let parent_fonts = ui.style().text_styles.clone();
+ let parent_wrap = ui.style().wrap_mode;
+ expected_ink = palette.map_or(authored.panel, |tokens| tokens.text);
+ panel_host_surface(ui, egui::Id::unique("captured-fill"), bounds, floating, appearance.fill, palette, |ui, clip| {
+ assert_eq!(Tokens::get(), palette.copied().unwrap_or(authored));
+ assert_eq!(ui.spacing().item_spacing, parent_spacing);
+ assert_eq!(ui.style().text_styles, parent_fonts);
+ assert_eq!(ui.style().override_font_id, Some(font.clone()));
+ assert_eq!(ui.style().wrap_mode, parent_wrap);
+ if palette.is_none() {
+ assert_eq!(ui.visuals(), &parent_visuals, "normal bodies inherit unchanged visuals");
+ }
+ assert!(bounds.contains_rect(clip));
+ ui.label("Readable captured panel");
+ });
+ assert_eq!(Tokens::get(), authored);
+ assert_eq!(ui.visuals(), &parent_visuals, "fallback visuals restore immediately");
+ assert_eq!(ui.spacing().item_spacing, parent_spacing);
+ assert_eq!(ui.style().text_styles, parent_fonts);
+ });
+ let (mut backgrounds, mut labels) = (0, 0);
+ for shape in &output.shapes {
+ crate::test_support::each_shape(&shape.shape, &mut |shape| match shape {
+ egui::Shape::Rect(rect) if rect.rect == bounds && rect.fill != egui::Color32::TRANSPARENT => {
+ assert_eq!(rect.fill, appearance.fill, "actual paint uses the captured fill");
+ backgrounds += 1;
+ }
+ egui::Shape::Text(text) if text.galley.job.text == "Readable captured panel" => {
+ for section in &text.galley.job.sections {
+ let ink = text.override_text_color.unwrap_or_else(|| {
+ if section.format.color == egui::Color32::PLACEHOLDER { text.fallback_color } else { section.format.color }
+ });
+ assert_eq!(ink, expected_ink, "the actual plain-label galley uses readable fallback ink");
+ assert_eq!(section.format.font_id, font, "fallback preserves the body's chosen font");
+ }
+ labels += 1;
+ }
+ _ => {}
+ });
+ }
+ assert!(backgrounds > 0 && labels > 0, "inspect real background and label paint");
+ assert_eq!(Tokens::get(), authored);
+ }
+ }
+}
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index 521bb91f02..d16e1bbb33 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -263,7 +263,7 @@ actual current Session without another service tick. Runtime inspection remains
read-only. The shared host adds no production command registration beyond the
application-layout commands above.
-For native host evidence, `ui.panel_fixture {enabled?, preset?, remember?}` installs bounded
+For native host evidence, `ui.panel_fixture {enabled?, preset?, remember?, translucency_percent?}` installs bounded
synthetic content in the real `SolveApp` workspace host. The normal connection
authentication applies. It is off by default and ephemeral unless explicitly
enabled with `remember:true`. It adds no design change, production content
@@ -275,12 +275,14 @@ registration or native panel window.
| `{"enabled":true}` | Enable the `docks` specimen if no runtime exists. |
| `{"preset":"tabs"}` | Enable the named specimen if no runtime exists. |
| `{"preset":"tabs","remember":true}` | Enable the specimen and its application preference catalogue. Restore a saved record after valid host dimensions are available. |
+| `{"preset":"surfaces","translucency_percent":50}` | Enable declared surface-policy specimens with a runtime-only translucency request (finite 0–100 percent). Readability may raise effective opacity. |
+| `{"translucency_percent":100}` | Change the enabled specimen's request without replacing controllers, drafts or layout. Refuse if no specimen owns the host. |
| `{"enabled":false}` | Preflight and tear down only the specimen runtime; refusal leaves it intact. |
Presets are `docks` (Left/Right/Bottom, with two Left sections), `tabs` (two groups
of two), `collapsed` (four full-width collapsed headers), `floating` (four in-app floating
sections), `overflow` (24 instances), and `pinned` (an outer pinned Right section
-plus ordinary docks), `columns` (three independent Left columns), `stack_tabs`, `content_fill` (sole Content versus Fill), and `inline` (one editable total row). The retired `rails` preset is rejected. Original synthetic content retains editable drafts and
+plus ordinary docks), `columns` (three independent Left columns), `stack_tabs`, `content_fill` (sole Content versus Fill), `inline` (one editable total row), and `surfaces` (mixed tab and explicit surface policies). Only `surfaces` opts out of compatibility opaque presentation. Requested opacity is `1 - translucency_percent / 100`; the override never changes saved preferences. The retired `rails` preset is rejected. Original synthetic content retains editable drafts and
controller state across hiding and moves. Services keep ticking while content is
hidden. Apply/Finish/Cancel are synthetic actions; the Session is never passed to
their command sink. The editor's cancellation guard checkbox can refuse explicit
diff --git a/docs/panel-foundation.md b/docs/panel-foundation.md
index 1784a29d14..2c3d88f25b 100644
--- a/docs/panel-foundation.md
+++ b/docs/panel-foundation.md
@@ -306,18 +306,20 @@ reparent the window.
The default adapter truthfully advertises no native windows. Actual Window
placement needs the native sibling's monitor/DPI, focus and close/redock services.
-The renderer retains the shared Container's fill alpha; captured `paint_alpha`
-reports it separately from declarative surface intent. Input and occlusion remain
-reserved regardless of alpha. Unsupported translucent effective policies still
-refuse. Contrast proof, comprehensive accessibility/keyboard bindings, production
-workspace rollout and real content adapters remain their named peers' work.
+The renderer resolves surface intent through the shared Container, raising its
+fill alpha when canonical text needs more contrast. Captured `paint_alpha` and
+`contrast` report the effective paint and any readable fallback separately from
+declarative intent. Input and occlusion remain reserved regardless of alpha.
+Comprehensive accessibility/keyboard bindings, production workspace rollout and
+real content adapters remain their named peers' work.
## Specimens and verification boundary
`ui.panel_fixture` is authenticated, off by default, and refuses to replace another
runtime. Presets: `docks`, `tabs`, `collapsed`, `floating`, `overflow` (24 instances),
`pinned`, `columns` (three independent Left columns), `stack_tabs`, `content_fill`
-(short Content versus Fill), and `inline` (one editable total row). The old `rails`
+(short Content versus Fill), `inline` (one editable total row), and `surfaces`
+(declared surface preferences with the existing synthetic bodies). The old `rails`
preset is replaced by `collapsed`; it is not an alias to the retired experience.
The optional `remember:true` enable parameter attaches the application preference
catalogue for isolated restart review. A restart must explicitly enable the same
@@ -325,6 +327,50 @@ specimen with `remember:true`; loading preferences alone never starts it. Saved
restoration waits for valid host dimensions and uses normal runtime admission.
Fixture workspace/preset registrations remain synthetic evidence, not shipping
production registrations.
+
+### Surface review specimen
+
+The `surfaces` preset alone opts out of the host's compatibility opaque default.
+It contains an inactive text-heavy editor tab beside an active log tab, explicit
+Opaque and Translucent side members, and FollowZone Bottom and Floating members.
+The same existing content, commands and translated captions remain in use.
+Other presets retain their previous opaque presentation.
+
+`ui.panel_fixture {"preset":"surfaces","translucency_percent":50}` requests
+50% translucency for this explicitly enabled specimen. The optional value is a
+finite number from 0 to 100; opacity is `1 - translucency_percent / 100`.
+Zero requests an opaque surface and 100 requests a fully transparent surface
+before readability protection. The override is not a saved preference.
+`ui.panel_fixture {"translucency_percent":100}` updates the already enabled
+specimen host in place, preserving retained controllers, drafts and layout.
+It refuses when no specimen host is enabled or another provider owns the runtime.
+The parameter is also accepted with other explicitly enabled specimen presets;
+their compatibility opaque policy still applies. Omitting the
+override uses current theme/preferences rather than a specimen colour palette.
+
+Surface resolution uses every registered tab's metadata, including inactive tabs.
+Explicit Opaque wins, then explicit Translucent. Otherwise FollowZone is opaque
+for Bottom/Window or a multi-tab group containing a text-heavy member, and
+translucent elsewhere. Effective opacity may increase to protect both primary
+and muted text at 4.5:1 over possible viewport backgrounds. When the authored
+token pair cannot meet that guarantee even at full opacity, the renderer uses a
+known accessible opaque fallback pair and reports the failure, rather than
+describing the authored pair as compliant. Existing blur infrastructure remains
+independent of opacity and input capture.
+
+Section inspection reports declarative `surface`, actual `paint_alpha`, and
+optional `contrast`. The latter preserves `ContrastOutcome`, including the
+fallback reason; fallback is not a successful proof for the original pair.
+Actual clipped surface footprints continue to own input even when translucent.
+Uncovered short-panel gaps remain navigable, while content scrolling and actual
+controls shield the model. Temporary popup shielding is not a Fit/Centre obstacle.
+
+This is shared surface policy and an opt-in review seam, not a production content
+migration or a new appearance preset. Classic and shipping defaults remain.
+Future approved docked adapters are Browser, History, Assistant and their allowed
+RenderSceneBrowser counterpart; other content conversions require a separate
+scope decision. Persistent legacy forms retain their existing hosts and continue
+to contribute their actual footprints until their own migrations.
The original synthetic controllers expose draft, transaction, action, lifecycle,
render and service counters plus process-local equality tokens. They do not expose
fake production actions or pretend to perform CAD work.
diff --git a/docs/ui-kit.md b/docs/ui-kit.md
index 8b39f2001b..b1a9a8f01a 100644
--- a/docs/ui-kit.md
+++ b/docs/ui-kit.md
@@ -99,12 +99,24 @@ adapter while native placements exist. The default adapter truthfully supplies n
native Window service. Host cards reuse adaptive Container styling, title fonts,
the six-dot grip and header separator. Shared shell gaps are allocation space.
Captured frame alpha is reported separately from declarative surface intent;
-unsupported effective translucency still refuses. Native windows, contrast proof, comprehensive accessibility/keyboard
+the opt-in surface renderer reports contrast outcomes and raises opacity to retain
+readable primary and muted text. An invalid authored pair uses an opaque accessible
+fallback and reports its reason rather than claiming the original pair complies.
+Native windows, comprehensive accessibility/keyboard
bindings, saved workspace rollout and real content migrations remain peer work.
The authenticated `ui.panel_fixture` seam is off by default and rejects replacing
an existing runtime. Presets are `docks`, `tabs`, `collapsed`, `floating`, `overflow`
-(24 instances), `pinned`, `columns`, `stack_tabs`, `content_fill` and `inline`.
+(24 instances), `pinned`, `columns`, `stack_tabs`, `content_fill`, `inline` and `surfaces`.
+Only `surfaces` opts out of the compatibility opaque host policy. Its optional
+`translucency_percent` request (finite 0–100) converts to opacity as
+`1 - percent / 100`; readability protection may increase effective opacity.
+This fixture override changes no saved preference. Inspection reports each
+section's declared `surface`, actual `paint_alpha` and optional `contrast` outcome,
+including fallback reasons. See [the surface specimen contract](panel-foundation.md#surface-review-specimen).
+An enabled specimen accepts `translucency_percent` alone to update presentation
+in place, retaining its controllers, drafts, layout and model. A missing/disabled
+specimen host or a runtime owned by another provider refuses this update.
Drafts, controller identities and lifecycle/service/action counters are inspectable.
The native specimen exposes editor Apply/Finish/Cancel actions. Separate
action-binding fixtures retain their declared test actions.