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.rsindex 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.rsindex 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.rsindex 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, ¶ms).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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsnew file mode 100644index 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.rsindex 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_invalidatesh.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.rsindex 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(§ion.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, §ion.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.rsindex 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::Availabfn 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.rsindex 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.rsindex 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.rsindex 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);resultdiff --git a/crates/ui-egui/src/ui_kit/panel_tests.rs b/crates/ui-egui/src/ui_kit/panel_tests.rsindex 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_foclet 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_contentif 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.mdindex 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 remainsread-only. The shared host adds no production command registration beyond theapplication-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 boundedsynthetic content in the real `SolveApp` workspace host. The normal connectionauthentication applies. It is off by default and ephemeral unless explicitlyenabled 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 groupsof two), `collapsed` (four full-width collapsed headers), `floating` (four in-app floatingsections), `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 andcontroller state across hiding and moves. Services keep ticking while content ishidden. Apply/Finish/Cancel are synthetic actions; the Session is never passed totheir command sink. The editor's cancellation guard checkbox can refuse explicitdiff --git a/docs/panel-foundation.md b/docs/panel-foundation.mdindex 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 Windowplacement 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 anotherruntime. 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 preferencecatalogue 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. Savedrestoration waits for valid host dimensions and uses normal runtime admission.Fixture workspace/preset registrations remain synthetic evidence, not shippingproduction 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 exposefake production actions or pretend to perform CAD work.diff --git a/docs/ui-kit.md b/docs/ui-kit.mdindex 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 nnative 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/keyboardbindings, saved workspace rollout and real content migrations remain peer work.The authenticated `ui.panel_fixture` seam is off by default and rejects replacingan 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. Separateaction-binding fixtures retain their declared test actions.