From 5c93b787047b00caff535c7b1209672573630192 Mon Sep 17 00:00:00 2001 From: CRT Date: Tue, 29 Sep 2026 13:07:59 +0700 Subject: [PATCH] runtime + host: the theme engine (theme documents, choice catalog, page runtime, fonts; native theme state) The site-independent theme engine moves from wayBetter for X into the framework: - runtime/themeSpec.ts: theme document types, the schema's defaults (BASE_*), sanitizing, import, overrides, ensureContrast, font roles/stacks, font choices, backgrounds. - runtime/themeChoice.ts: ThemeChoice and createThemeCatalog(builtins) (normalize, base, resolve, palette, all), choiceForId, serializeChoice. - runtime/themeRuntime.ts: installThemeRuntime(win, site) (live CSS over the site's rules, --wb-* vars, site color mode, first-frame snapshot), collectRules, resolvedFonts. - runtime/fonts.ts: bundled fonts and owner-downloaded Google Fonts from bytes. - themeApi exports hexToRgb, mix and MONO_FAMILIES (one copy: themeTokens and themeSpec use them). - host theme.rs: ThemeChoice/ThemeScopes over a site's ThemeSite (envelope checks against theme.schema.json, which theme a tab shows, page color, delivery script). --- crates/waybetter-host/src/lib.rs | 3 + crates/waybetter-host/src/theme.rs | 410 ++++++++++++++++ packages/runtime/src/fonts.ts | 73 +++ packages/runtime/src/themeApi.ts | 22 +- packages/runtime/src/themeChoice.ts | 79 ++++ packages/runtime/src/themeRuntime.ts | 243 ++++++++++ packages/runtime/src/themeSpec.ts | 521 +++++++++++++++++++++ packages/runtime/src/themeTokens.ts | 6 +- packages/runtime/tests/themeEngine.test.ts | 199 ++++++++ 9 files changed, 1542 insertions(+), 14 deletions(-) create mode 100644 crates/waybetter-host/src/theme.rs create mode 100644 packages/runtime/src/fonts.ts create mode 100644 packages/runtime/src/themeChoice.ts create mode 100644 packages/runtime/src/themeRuntime.ts create mode 100644 packages/runtime/src/themeSpec.ts create mode 100644 packages/runtime/tests/themeEngine.test.ts diff --git a/crates/waybetter-host/src/lib.rs b/crates/waybetter-host/src/lib.rs index 0d2563b..b67d5e6 100644 --- a/crates/waybetter-host/src/lib.rs +++ b/crates/waybetter-host/src/lib.rs @@ -19,6 +19,8 @@ //! - [`i18n`]: the strings native UI and site tabs get in the owner's language (validated data), OS locale. //! - [`backup`]: the settings backup envelope, secret scrubbing and the plugin/account sections. //! - [`sync`]: encrypted settings sync through a folder the owner syncs (Argon2id + XChaCha20-Poly1305). +//! - [`theme`]: the owner's theme choice and account/pane themes (envelope checks, which theme a tab +//! shows, its page color and delivery script) over a site's built-in themes. //! - [`workspaces`]: saved tab/pane/deck layouts, bounded and well-formed (never evaluated). //! - [`devmode`]: developer mode's debounced watcher of plugins, custom CSS and a theme file. //! - [`alerts`]: local keyword alerts (keywords, snippets, per-item/per-keyword rate limits). @@ -57,6 +59,7 @@ pub mod store; pub mod sync; pub mod tabs; pub mod testkit; +pub mod theme; pub mod update; pub mod workspaces; diff --git a/crates/waybetter-host/src/theme.rs b/crates/waybetter-host/src/theme.rs new file mode 100644 index 0000000..dfd5425 --- /dev/null +++ b/crates/waybetter-host/src/theme.rs @@ -0,0 +1,410 @@ +//! The owner's theme state as native code keeps it: the theme choice (a theme id, an accent, the +//! panel's per-group overrides and the owner's imported theme documents; `x-theme.v2.json` style +//! app data) and which theme each site tab shows ([`ThemeScopes`]: a pane's own theme, else its +//! account profile's, else the global one). The same rules run in the shell +//! (`waybetter/packages/runtime/src/themeChoice.ts`, `shell/src/frame/themeScopes.ts`). +//! +//! Theme documents are declarative JSON (`theme.schema.json` in the `waybetter` package) that the page +//! runtime sanitizes field by field (`runtime/src/themeSpec.ts`: hex colors, clamped numbers, fixed +//! enums, font names matching a strict pattern, `data:image/*` backgrounds). Here only the envelope is +//! checked against the schema's own rules (ids, names, sizes, override groups), so nothing unbounded +//! is persisted or evaluated in every site tab. What differs per site is its built-in themes +//! ([`ThemeSite`]). + +use crate::site::SiteSpec; +use serde::{Deserialize, Serialize}; +use serde_json::{Map, Value}; +use std::collections::BTreeMap; + +/// A site's built-in themes. The first preset is the site's own look (the default choice). +#[derive(Clone, Copy, Debug)] +pub struct ThemeSite { + /// Built-in theme ids the page runtime knows (the site's `BUILTIN_THEMES`), its own look first. + pub presets: &'static [&'static str], + /// The page color (`colors.page`, else `colors.bg`) of every built-in theme with colors of its + /// own: a tab webview's native background before the page paints. The site's own look has none. + pub page_colors: &'static [(&'static str, &'static str)], +} + +impl ThemeSite { + /// The site's own look (`presets[0]`). + pub fn own(&self) -> &'static str { + self.presets.first().copied().unwrap_or("site") + } +} + +/// At most this many imported/user themes are kept (`MAX_USER_THEMES` in themeChoice.ts). +pub const MAX_THEMES: usize = 24; +/// One theme document (a background image is a `data:` URL inside it). +pub const MAX_THEME_BYTES: usize = 1_200_000; +/// The whole persisted theme state, all themes included. +pub const MAX_TOTAL_BYTES: usize = 4_000_000; +/// Theme names: 1-60 characters (`theme.schema.json` `name`). +pub const MAX_NAME_CHARS: usize = 60; +/// Override groups the panel may change on top of a theme. +pub const OVERRIDE_KEYS: [&str; 7] = ["font", "shape", "layout", "background", "effects", "colors", "css"]; + +/// The theme applied to the site's tabs: a theme id (built-in or one of `themes`), an optional +/// accent, per-group overrides from the panel and the owner's imported theme documents. +#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] +#[serde(rename_all = "camelCase", deny_unknown_fields)] +pub struct ThemeChoice { + pub preset: String, + #[serde(default)] + pub accent: Option, + #[serde(default, skip_serializing_if = "Map::is_empty")] + pub overrides: Map, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub themes: Vec, +} + +/// A theme id: a lowercase slug of 1-40 characters (`theme.schema.json` `id`). +pub fn valid_id(id: &str) -> bool { + !id.is_empty() && id.len() <= 40 && id.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-') +} + +/// A six-digit `#rrggbb` color. +pub fn valid_hex(value: &str) -> bool { + value.len() == 7 && value.starts_with('#') && value.as_bytes()[1..].iter().all(u8::is_ascii_hexdigit) +} + +fn doc_id(theme: &Value) -> Option<&str> { + theme.get("id").and_then(Value::as_str) +} + +impl ThemeChoice { + /// The site's own look, nothing customized. + pub fn default_for(site: &ThemeSite) -> Self { + Self { preset: site.own().into(), accent: None, overrides: Map::new(), themes: Vec::new() } + } + + pub fn validate(&self, site: &ThemeSite) -> Result<(), String> { + if let Some(accent) = &self.accent { + if !valid_hex(accent) { + return Err("VALIDATION: accent must use six-digit hex".into()); + } + } + if self.themes.len() > MAX_THEMES { + return Err("VALIDATION: too many themes".into()); + } + let mut ids: Vec<&str> = Vec::new(); + for theme in &self.themes { + let object = theme.as_object().ok_or("VALIDATION: a theme must be an object")?; + let id = object.get("id").and_then(Value::as_str).ok_or("VALIDATION: a theme needs an id")?; + if !valid_id(id) || site.presets.contains(&id) || ids.contains(&id) { + return Err("VALIDATION: theme ids are unique lowercase slugs".into()); + } + let name = object.get("name").and_then(Value::as_str).ok_or("VALIDATION: a theme needs a name")?; + if name.trim().is_empty() || name.chars().count() > MAX_NAME_CHARS { + return Err("VALIDATION: theme names are 1-60 characters".into()); + } + if serde_json::to_vec(theme).map(|bytes| bytes.len()).unwrap_or(usize::MAX) > MAX_THEME_BYTES { + return Err("VALIDATION: theme is too large".into()); + } + ids.push(id); + } + if !site.presets.contains(&self.preset.as_str()) && !ids.contains(&self.preset.as_str()) { + return Err("VALIDATION: unknown theme preset".into()); + } + for (key, value) in &self.overrides { + if !OVERRIDE_KEYS.contains(&key.as_str()) || !value.is_object() { + return Err("VALIDATION: unknown theme override".into()); + } + } + if serde_json::to_vec(self).map(|bytes| bytes.len()).unwrap_or(usize::MAX) > MAX_TOTAL_BYTES { + return Err("VALIDATION: theme data is too large".into()); + } + Ok(()) + } + + /// True when the site keeps its own look (nothing to apply). Imported themes are kept in the + /// file even while the site's own look is selected, so this only looks at what is applied. + pub fn is_default(&self, site: &ThemeSite) -> bool { + self.preset == site.own() && self.accent.is_none() && self.overrides.is_empty() + } + + /// Nothing worth persisting: the site's own look and no imported themes. + pub fn is_empty(&self, site: &ThemeSite) -> bool { + self.is_default(site) && self.themes.is_empty() + } + + /// Whether `id` names a theme this state knows (built-in or imported). + pub fn knows(&self, site: &ThemeSite, id: &str) -> bool { + site.presets.contains(&id) || self.themes.iter().any(|theme| doc_id(theme) == Some(id)) + } + + /// The state a tab gets when it shows theme `id`: this state itself for the global theme, else + /// that theme document without the global customizations. Only the document shown is sent. + pub fn for_theme(&self, site: &ThemeSite, id: &str) -> ThemeChoice { + let base = if id == self.preset || !self.knows(site, id) { + self.clone() + } else { + ThemeChoice { preset: id.into(), accent: None, overrides: Map::new(), themes: self.themes.clone() } + }; + let preset = base.preset.clone(); + let themes = base.themes.into_iter().filter(|theme| doc_id(theme) == Some(preset.as_str())).collect(); + ThemeChoice { themes, ..base } + } + + /// Google Fonts families (`font.roles.*` with `"source": "google"`) the shown theme uses in the + /// site's page, from its document and the global overrides. Names are checked again when read from disk. + pub fn google_fonts(&self) -> Vec { + let mut out: Vec = Vec::new(); + let doc = self.themes.iter().find(|theme| doc_id(theme) == Some(self.preset.as_str())); + let mut collect = |font: Option<&Value>| { + let Some(roles) = font.and_then(|font| font.get("roles")).and_then(Value::as_object) else { return }; + for (role, spec) in roles { + if role == "chrome" || spec.get("source").and_then(Value::as_str) != Some("google") { + continue; + } + if let Some(family) = spec.get("family").and_then(|family| family.get(0)).and_then(Value::as_str) { + if crate::gfonts::valid_family(family) && !out.iter().any(|seen| seen == family) && out.len() < 8 { + out.push(family.to_owned()); + } + } + } + }; + collect(doc.and_then(|doc| doc.get("font"))); + collect(self.overrides.get("font")); + out + } + + /// The color the shown theme paints the site's page with, as RGB: the tab webview's native + /// background, so a new tab, a navigation or a pane growing during a drag never shows the + /// WebView's white before the page paints. `None` for the site's own look (the site picks it). + pub fn page_color(&self, site: &ThemeSite) -> Option<(u8, u8, u8)> { + let colors_of = |value: Option<&Value>| { + let colors = value?.get("colors")?; + ["page", "bg"].iter().find_map(|key| colors.get(*key).and_then(Value::as_str).filter(|hex| valid_hex(hex)).map(str::to_owned)) + }; + let doc = self.themes.iter().find(|theme| doc_id(theme) == Some(self.preset.as_str())); + let base = match doc { + Some(doc) => colors_of(Some(doc)), + None => site.page_colors.iter().find(|(id, _)| *id == self.preset).map(|(_, hex)| (*hex).to_owned()), + }?; + // Color overrides apply only on top of a theme with colors of its own (like the runtime). + let hex = colors_of(Some(&Value::Object(self.overrides.clone()))).unwrap_or(base); + let channel = |at: usize| u8::from_str_radix(&hex[at..at + 2], 16).ok(); + Some((channel(1)?, channel(3)?, channel(5)?)) + } + + /// Hands the theme to the page runtime (`.theme.apply`), or leaves it for the runtime to + /// pick up at start (`__btTheme`); only in the top frame of the site's own origin. + pub fn script(&self, site: &ThemeSite, spec: &SiteSpec) -> Result { + self.validate(site)?; + let json = serde_json::to_string(self).map_err(|_| "THEME: serialization failed")?; + Ok(format!( + "(()=>{{if(window.top!==window||location.origin!=='{origin}')return;const t={json};const BT=window.{global};if(BT&&BT.theme)BT.theme.apply(t);else window.__btTheme=t;}})();", + origin = spec.primary_origin(), + global = spec.runtime_global, + )) + } +} + +/// At most this many account profiles and panes carry a theme of their own. +pub const MAX_PROFILE_THEMES: usize = 32; +pub const MAX_PANE_THEMES: usize = 64; + +/// Which theme each site tab gets: a pane's own theme, else its account profile's, else the global +/// one. `chrome` says whether wayBetter's own window follows the theme (`"theme"`) or keeps its own +/// style (`"own"`); only the shell reads it. +#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] +#[serde(rename_all = "camelCase", deny_unknown_fields)] +pub struct ThemeScopes { + #[serde(default = "chrome_default")] + pub chrome: String, + #[serde(default)] + pub profiles: BTreeMap, + #[serde(default)] + pub panes: BTreeMap, +} + +impl Default for ThemeScopes { + fn default() -> Self { + Self { chrome: chrome_default(), profiles: BTreeMap::new(), panes: BTreeMap::new() } + } +} + +fn chrome_default() -> String { + "theme".into() +} + +impl ThemeScopes { + pub fn validate(&self) -> Result<(), String> { + if self.chrome != "theme" && self.chrome != "own" { + return Err("VALIDATION: chrome must be theme or own".into()); + } + if self.profiles.len() > MAX_PROFILE_THEMES || self.panes.len() > MAX_PANE_THEMES { + return Err("VALIDATION: too many theme assignments".into()); + } + for (profile, theme) in &self.profiles { + if !crate::profiles::valid_profile_id(profile) || !valid_id(theme) { + return Err("VALIDATION: invalid account theme".into()); + } + } + for (tab, theme) in &self.panes { + if !crate::policy::valid_tab_id(tab) || !valid_id(theme) { + return Err("VALIDATION: invalid pane theme".into()); + } + } + Ok(()) + } + + /// Nothing worth persisting. + pub fn is_default(&self) -> bool { + self.chrome == "theme" && self.profiles.is_empty() && self.panes.is_empty() + } + + /// The theme id tab `tab` (in account `profile`) shows; unknown ids fall through to the next level. + pub fn theme_id<'a>(&'a self, site: &ThemeSite, global: &'a ThemeChoice, tab: &str, profile: Option<&str>) -> &'a str { + if let Some(id) = self.panes.get(tab).filter(|id| global.knows(site, id)) { + return id; + } + if let Some(id) = profile.and_then(|profile| self.profiles.get(profile)).filter(|id| global.knows(site, id)) { + return id; + } + &global.preset + } + + /// The theme state for one site tab. + pub fn for_tab(&self, site: &ThemeSite, global: &ThemeChoice, tab: &str, profile: Option<&str>) -> ThemeChoice { + global.for_theme(site, self.theme_id(site, global, tab, profile)) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + static SITE: ThemeSite = ThemeSite { + presets: &["site", "paper", "nord", "night-ink"], + page_colors: &[("paper", "#e9e2d3"), ("nord", "#232831"), ("night-ink", "#05060a")], + }; + + fn with(value: Value) -> Result { + let theme: ThemeChoice = serde_json::from_value(value).map_err(|error| error.to_string())?; + theme.validate(&SITE).map(|()| theme) + } + + #[test] + fn page_color_follows_the_shown_theme() { + let preset = |id: &str| ThemeChoice { preset: id.into(), ..ThemeChoice::default_for(&SITE) }; + assert_eq!(preset("site").page_color(&SITE), None, "the site's own look: the site picks its palette"); + assert_eq!(preset("nord").page_color(&SITE), Some((0x23, 0x28, 0x31))); + let overridden = ThemeChoice { overrides: json!({ "colors": { "page": "#102030" } }).as_object().unwrap().clone(), ..preset("nord") }; + assert_eq!(overridden.page_color(&SITE), Some((0x10, 0x20, 0x30))); + let own_with_override = ThemeChoice { overrides: json!({ "colors": { "page": "#102030" } }).as_object().unwrap().clone(), ..preset("site") }; + assert_eq!(own_with_override.page_color(&SITE), None, "the site's own look ignores color overrides"); + let imported = ThemeChoice { + preset: "mine".into(), + themes: vec![json!({ "id": "mine", "name": "Mine", "colors": { "bg": "#abcdef", "page": "nope" } })], + ..ThemeChoice::default_for(&SITE) + }; + assert_eq!(imported.page_color(&SITE), Some((0xab, 0xcd, 0xef)), "an invalid page color falls back to bg"); + } + + #[test] + fn user_themes_and_overrides_are_bounded() { + let ok = with(json!({ "preset": "mine", "themes": [{ "id": "mine", "name": "Mine", "colors": null }], "overrides": { "font": { "scale": 1.1 } } })).unwrap(); + assert!(!ok.is_default(&SITE)); + let script = ok.script(&SITE, &crate::site::testing::SITE).unwrap(); + assert!(script.contains(r#""preset":"mine""#)); + assert!(script.starts_with("(()=>{if(window.top!==window||location.origin!=='https://x.com')return;"), "{script}"); + assert!(script.contains("const BT=window.BetterTwttr;")); + assert!(with(json!({ "preset": "other", "themes": [{ "id": "mine", "name": "Mine" }] })).is_err(), "the selected theme must exist"); + for id in ["Mine", "a b", "", "site", "night-ink", ""] { + assert!(with(json!({ "preset": "site", "themes": [{ "id": id, "name": "n" }] })).is_err(), "accepted {id}"); + } + assert!(with(json!({ "preset": "site", "themes": [{ "id": "a", "name": "A" }, { "id": "a", "name": "B" }] })).is_err()); + assert!(with(json!({ "preset": "site", "themes": [{ "id": "a", "name": "" }] })).is_err()); + assert!(with(json!({ "preset": "site", "themes": ["css"] })).is_err()); + assert!(with(json!({ "preset": "site", "overrides": { "script": {} } })).is_err()); + assert!(with(json!({ "preset": "site", "overrides": { "css": { "text": "a { color: red }" } } })).is_ok(), "theme CSS override"); + assert!(with(json!({ "preset": "site", "overrides": { "css": "a {}" } })).is_err(), "theme CSS must be an object"); + assert!(with(json!({ "preset": "site", "overrides": { "font": "Comic Sans" } })).is_err()); + let huge = "a".repeat(MAX_THEME_BYTES); + assert!(with(json!({ "preset": "site", "themes": [{ "id": "a", "name": "A", "css": huge }] })).is_err()); + let many: Vec = (0..=MAX_THEMES).map(|i| json!({ "id": format!("t{i}"), "name": "T" })).collect(); + assert!(with(json!({ "preset": "site", "themes": many })).is_err()); + } + + #[test] + fn tabs_get_pane_then_account_then_global_theme() { + let global = with(json!({ "preset": "mine", "accent": "#ff0000", "overrides": { "font": { "scale": 1.1 } }, + "themes": [{ "id": "mine", "name": "Mine" }, { "id": "other", "name": "Other" }] })).unwrap(); + let scopes: ThemeScopes = serde_json::from_value(json!({ "profiles": { "p1": "paper" }, "panes": { "t1": "other", "t2": "gone" } })).unwrap(); + scopes.validate().unwrap(); + assert_eq!(scopes.chrome, "theme"); + assert_eq!(scopes.theme_id(&SITE, &global, "t1", Some("p1")), "other"); + assert_eq!(scopes.theme_id(&SITE, &global, "t2", Some("p1")), "paper"); + assert_eq!(scopes.theme_id(&SITE, &global, "t2", Some("default")), "mine"); + assert_eq!(scopes.theme_id(&SITE, &global, "t3", None), "mine"); + // The global theme keeps its customizations; another theme is sent bare and alone. + let same = scopes.for_tab(&SITE, &global, "t9", None); + assert_eq!((same.accent.as_deref(), same.overrides.len(), same.themes.len()), (Some("#ff0000"), 1, 1)); + let other = scopes.for_tab(&SITE, &global, "t1", None); + assert_eq!((other.preset.as_str(), other.accent.as_deref(), other.overrides.len(), other.themes.len()), ("other", None, 0, 1)); + other.validate(&SITE).unwrap(); + let builtin = scopes.for_tab(&SITE, &global, "t5", Some("p1")); + assert_eq!((builtin.preset.as_str(), builtin.themes.len()), ("paper", 0)); + builtin.validate(&SITE).unwrap(); + } + + #[test] + fn scopes_are_bounded_and_checked() { + let parse = |value: Value| serde_json::from_value::(value).map_err(|e| e.to_string()).and_then(|s| s.validate().map(|()| s)); + assert!(parse(json!({})).unwrap().is_default()); + assert!(parse(json!({ "chrome": "own" })).is_ok()); + assert!(parse(json!({ "chrome": "rainbow" })).is_err()); + assert!(parse(json!({ "panes": { "t1": "Night Ink" } })).is_err(), "theme ids are slugs"); + assert!(parse(json!({ "panes": { "../t": "paper" } })).is_err(), "tab ids are checked"); + assert!(parse(json!({ "profiles": { "work": "paper" } })).is_err(), "profile ids are checked"); + assert!(parse(json!({ "script": {} })).is_err(), "unknown fields"); + let many: Map = (0..=MAX_PANE_THEMES).map(|i| (format!("t{i}"), json!("paper"))).collect(); + assert!(parse(json!({ "panes": many })).is_err()); + } + + #[test] + fn google_fonts_come_from_the_shown_theme_only() { + let global = with(json!({ "preset": "mine", "overrides": { "font": { "roles": { "numbers": { "family": ["Space Mono"], "source": "google" } } } }, + "themes": [ + { "id": "mine", "name": "Mine", "font": { "roles": { + "interface": { "family": ["Inter", "sans-serif"], "source": "google" }, + "post": { "family": ["Georgia"] }, + "chrome": { "family": ["Fraunces"], "source": "google" }, + "heading": { "family": ["../../evil"], "source": "google" } } } }, + { "id": "other", "name": "Other", "font": { "roles": { "post": { "family": ["Lora"], "source": "google" } } } } + ] })).unwrap(); + // Chrome fonts are the shell's; invalid names are dropped; overrides count. + assert_eq!(global.google_fonts(), vec!["Inter".to_string(), "Space Mono".to_string()]); + assert_eq!(global.for_theme(&SITE, "other").google_fonts(), vec!["Lora".to_string()]); + assert!(global.for_theme(&SITE, "paper").google_fonts().is_empty()); + } + + #[test] + fn default_and_empty() { + let own = ThemeChoice::default_for(&SITE); + assert!(own.is_default(&SITE) && own.is_empty(&SITE)); + assert_eq!(own.preset, "site"); + let kept = with(json!({ "preset": "site", "themes": [{ "id": "a", "name": "A" }] })).unwrap(); + assert!(kept.is_default(&SITE) && !kept.is_empty(&SITE)); + } + + /// The envelope checks are the theme file's JSON Schema (`waybetter/theme.schema.json`). + #[test] + fn envelope_rules_are_the_schema_rules() { + let schema: Value = serde_json::from_str(include_str!("../../../packages/waybetter/theme.schema.json")).unwrap(); + let properties = schema["properties"].as_object().unwrap(); + assert_eq!(schema["properties"]["id"]["pattern"], "^[a-z0-9-]{1,40}$"); + assert_eq!(schema["properties"]["name"]["maxLength"], MAX_NAME_CHARS); + for group in OVERRIDE_KEYS { + assert!(properties.contains_key(group), "{group} is a theme document group"); + } + assert_eq!(schema["required"], json!(["name"])); + let long = "a".repeat(41); + for (id, ok) in [("a", true), ("night-ink-2", true), ("A", false), ("a_b", false), (long.as_str(), false)] { + assert_eq!(valid_id(id), ok, "{id}"); + } + } +} diff --git a/packages/runtime/src/fonts.ts b/packages/runtime/src/fonts.ts new file mode 100644 index 0000000..73747f0 --- /dev/null +++ b/packages/runtime/src/fonts.ts @@ -0,0 +1,73 @@ +// Theme fonts in a site's page. Sites usually block remote and `data:` font URLs (CSP `font-src`), +// but a FontFace built from bytes performs no fetch, so bundled families (Geist and Geist Mono: the +// app embeds their woff2 files in its page runtime) are registered only when a theme uses them, and +// Google Fonts the owner downloaded arrive as bytes from native code (`provideFonts`). + +import { BUNDLED_FONTS } from './themeSpec.ts'; + +/** Unicode ranges of the Latin and Latin Extended subsets (@fontsource file names `latin`, `latin-ext`). */ +export const LATIN_RANGE = 'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD'; +export const LATIN_EXT_RANGE = 'U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF'; + +/** A bundled family's files: base64 woff2 (variable, weights 100-900) with the unicode range each covers. */ +export type BundledFontFiles = Record>; + +const loaded = new WeakMap>(); +const log = (family: string, error: unknown) => console.error(`[wayBetter] font ${family} failed`, error); + +/** Registers the bundled families `names` (BUNDLED_FONTS) from `files`, once per document. */ +export function loadBundledFonts(doc: Document, names: string[], files: BundledFontFiles): void { + let done = loaded.get(doc); + if (!done) loaded.set(doc, done = new Set()); + for (const name of names) { + const faces = files[name]; + const family = BUNDLED_FONTS[name]; + if (!faces || !family || done.has(name)) continue; + done.add(name); + for (const [base64, unicodeRange] of faces) { + const bytes = Uint8Array.from(atob(base64), char => char.charCodeAt(0)); + const face = new FontFace(family, bytes.buffer, { weight: '100 900', style: 'normal', unicodeRange, display: 'swap' }); + doc.fonts.add(face); + face.load().catch(error => log(name, error)); + } + } +} + +/** + * Google Fonts the owner downloaded: native code validates and caches the woff2 files and hands + * their bytes to site tabs whose theme uses them. The page never requests a font; each family is + * registered once per document (again only when its bytes change, e.g. after picking other weights). + */ +export type ProvidedFont = { family: string; faces: Array<{ weight: [number, number]; unicodeRange: string | null; data: string }> }; +const provided = new WeakMap>(); +const FAMILY = /^[A-Za-z0-9][A-Za-z0-9 ]{0,47}$/; + +/** Registers the provided families (validated again; at most 8 families of 24 faces); returns the families added. */ +export function provideFonts(doc: Document, fonts: unknown): string[] { + const added: string[] = []; + if (!Array.isArray(fonts)) return added; + let known = provided.get(doc); + if (!known) provided.set(doc, known = new Map()); + for (const font of fonts.slice(0, 8) as ProvidedFont[]) { + if (!font || typeof font.family !== 'string' || !FAMILY.test(font.family) || !Array.isArray(font.faces)) continue; + const key = font.faces.map(face => `${face?.weight}|${typeof face?.data === 'string' ? face.data.length : 0}`).join(','); + if (known.get(font.family) === key) continue; + // Other weights of a family replace its earlier faces. + for (const face of [...doc.fonts]) if ((face as FontFace).family.replace(/"/g, '') === font.family && (face as FontFace & { wbGoogle?: boolean }).wbGoogle) doc.fonts.delete(face as FontFace); + known.set(font.family, key); + for (const face of font.faces.slice(0, 24)) { + if (!face || typeof face.data !== 'string' || !Array.isArray(face.weight)) continue; + try { + const bytes = Uint8Array.from(atob(face.data), char => char.charCodeAt(0)); + const [min, max] = face.weight.map(Number) as [number, number]; + const descriptors: FontFaceDescriptors = { weight: min === max ? String(min) : `${min} ${max}`, style: 'normal', display: 'swap' }; + if (typeof face.unicodeRange === 'string' && /^[U+0-9A-Fa-f?, -]{1,4000}$/.test(face.unicodeRange)) descriptors.unicodeRange = face.unicodeRange; + const fontFace = Object.assign(new FontFace(font.family, bytes.buffer, descriptors), { wbGoogle: true }); + doc.fonts.add(fontFace); + fontFace.load().catch(error => log(font.family, error)); + } catch (error) { log(font.family, error); } + } + added.push(font.family); + } + return added; +} diff --git a/packages/runtime/src/themeApi.ts b/packages/runtime/src/themeApi.ts index fd2256f..1db86f1 100644 --- a/packages/runtime/src/themeApi.ts +++ b/packages/runtime/src/themeApi.ts @@ -73,7 +73,9 @@ export type ResolvedFont = { inherited: boolean; }; export type ResolvedFonts = Record; -export const MONO_FONT = 'ui-monospace, "Cascadia Mono", "SF Mono", Consolas, Menlo, monospace'; +/** Monospaced families, in order: what a `mono` role that inherits (or a source without fonts) gets. */ +export const MONO_FAMILIES = ['Cascadia Mono', 'SF Mono', 'Consolas', 'Menlo', 'ui-monospace', 'monospace']; +export const MONO_FONT = MONO_FAMILIES.map(name => (/^(ui-monospace|monospace)$/.test(name) ? name : `"${name}"`)).join(', '); /** What a site adapter provides: the current resolved theme and change notifications. */ export type ThemeSource = { @@ -95,14 +97,15 @@ export const FALLBACK_FONT = 'system-ui, -apple-system, "Segoe UI", Roboto, Helv const HEX = /^#[0-9a-f]{6}$/i; -function channels(hex: string): [number, number, number] { +/** `#rrggbb` → [r, g, b]. */ +export function hexToRgb(hex: string): [number, number, number] { const n = parseInt(hex.slice(1, 7), 16); return [(n >> 16) & 255, (n >> 8) & 255, n & 255]; } /** WCAG relative luminance of `#rrggbb`. */ export function relativeLuminance(hex: string): number { - const [r, g, b] = channels(hex).map(v => { const c = v / 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; }) as [number, number, number]; + const [r, g, b] = hexToRgb(hex).map(v => { const c = v / 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; }) as [number, number, number]; return 0.2126 * r + 0.7152 * g + 0.0722 * b; } @@ -130,8 +133,9 @@ export function toHex(value: string | null | undefined): string | null { return `#${[match[1], match[2], match[3]].map(v => Math.min(255, Number(v)).toString(16).padStart(2, '0')).join('')}`; } -function mixHex(a: string, b: string, t: number): string { - const [x, y] = [channels(a), channels(b)]; +/** `a` moved toward `b` by `t` (0–1), per channel. */ +export function mix(a: string, b: string, t: number): string { + const [x, y] = [hexToRgb(a), hexToRgb(b)]; return `#${x.map((v, i) => Math.round(v + (y[i]! - v) * t).toString(16).padStart(2, '0')).join('')}`; } @@ -143,10 +147,10 @@ export function themeFromColors(bg: string, text: string, accent: string, extra: const dark = relativeLuminance(bg) < relativeLuminance(text); const colors: ResolvedColors = { bg, text, accent, - surface: mixHex(bg, text, dark ? 0.05 : 0.03), - elevated: mixHex(bg, text, dark ? 0.1 : 0.07), - border: mixHex(bg, text, dark ? 0.2 : 0.15), - muted: mixHex(bg, text, 0.62), + surface: mix(bg, text, dark ? 0.05 : 0.03), + elevated: mix(bg, text, dark ? 0.1 : 0.07), + border: mix(bg, text, dark ? 0.2 : 0.15), + muted: mix(bg, text, 0.62), onAccent: readableOn(accent), inverse: text, onInverse: bg, diff --git a/packages/runtime/src/themeChoice.ts b/packages/runtime/src/themeChoice.ts new file mode 100644 index 0000000..300eaa7 --- /dev/null +++ b/packages/runtime/src/themeChoice.ts @@ -0,0 +1,79 @@ +// The owner's theme choice: which theme document is on (a built-in one or an imported one), the +// panel's customizations on top of it and an accent override. Native code persists it and hands it +// to every site tab; the shell's theme store and the panel edit it. A site brings its built-in +// themes (`createThemeCatalog(builtins)`; the first one is the site's own look, the default). Pure. + +import { applyOverrides, isHex, sanitizeSpec, type Palette, type ThemeOverrides, type ThemeSpec } from './themeSpec.ts'; + +/** What is persisted natively and handed to the page runtime. */ +export type ThemeChoice = { preset: string; accent: string | null; overrides: ThemeOverrides; themes: ThemeSpec[] }; + +/** Imported themes kept in a choice (the JSON Schema of the native side says the same). */ +export const MAX_USER_THEMES = 24; +const OVERRIDE_GROUPS = ['colors', 'font', 'shape', 'layout', 'background', 'effects', 'css'] as const; + +export type ThemeCatalog = { + /** The site's built-in themes; the first is its own look (and the default choice). */ + builtins: readonly ThemeSpec[]; + /** Nothing chosen: the first built-in theme, no customizations. */ + defaultChoice: ThemeChoice; + /** Any JSON to a valid choice (imported themes sanitized, bounded and deduplicated; unknown ids fall back). */ + normalize(input: unknown): ThemeChoice; + /** The theme document a choice refers to (built-in or imported), before overrides. */ + base(choice: ThemeChoice): ThemeSpec; + /** The effective theme: the selected document with the panel's overrides and accent, legible. */ + resolve(choice: ThemeChoice): ThemeSpec; + /** The effective palette: the theme's colors (or none for the site's own) with the accent override applied. */ + palette(choice: ThemeChoice): Partial | null; + /** Every theme that can be picked: the built-in ones, then the choice's imported ones. */ + all(choice: ThemeChoice): ThemeSpec[]; +}; + +export function createThemeCatalog(builtins: readonly ThemeSpec[]): ThemeCatalog { + if (!builtins.length) throw new Error('wayBetter themes: a site needs at least one built-in theme (its own look)'); + const first = builtins[0]!; + const defaultChoice: ThemeChoice = { preset: first.id, accent: null, overrides: {}, themes: [] }; + const isBuiltin = (id: unknown) => builtins.some(item => item.id === id); + + function normalize(input: unknown): ThemeChoice { + const source = input && typeof input === 'object' ? input as Record : {}; + const themes: ThemeSpec[] = []; + if (Array.isArray(source.themes)) { + for (const raw of source.themes.slice(0, MAX_USER_THEMES)) { + const theme = sanitizeSpec(raw); + if (!isBuiltin(theme.id) && !themes.some(item => item.id === theme.id)) themes.push(theme); + } + } + const known = (id: unknown) => typeof id === 'string' && (isBuiltin(id) || themes.some(item => item.id === id)); + const preset = known(source.preset) ? source.preset as string : first.id; + const accent = isHex(source.accent) ? source.accent.toLowerCase() : null; + const overrides: ThemeOverrides = {}; + const rawOverrides = source.overrides && typeof source.overrides === 'object' ? source.overrides as Record : {}; + for (const key of OVERRIDE_GROUPS) { + const value = rawOverrides[key]; + if (value && typeof value === 'object' && !Array.isArray(value)) (overrides as Record)[key] = value; + } + return { preset, accent, overrides, themes }; + } + + const base = (choice: ThemeChoice) => choice.themes.find(item => item.id === choice.preset) ?? builtins.find(item => item.id === choice.preset) ?? first; + const resolve = (choice: ThemeChoice) => applyOverrides(base(choice), choice.overrides, choice.accent); + function palette(choice: ThemeChoice): Partial | null { + const theme = resolve(choice); + if (theme.colors) return theme.colors; + return choice.accent ? { accent: choice.accent } : null; + } + const all = (choice: ThemeChoice) => [...builtins, ...choice.themes]; + return { builtins, defaultChoice, normalize, base, resolve, palette, all }; +} + +/** The choice a tab's theme id stands for (themeScopes: account and pane themes): the global choice itself, or that theme without customizations. */ +export function choiceForId(global: ThemeChoice, id: string): ThemeChoice { + return id === global.preset ? global : { preset: id, accent: null, overrides: {}, themes: global.themes }; +} + +/** The shape persisted natively: empty groups are dropped so "no override" stays unambiguous. */ +export function serializeChoice(choice: ThemeChoice) { + const overrides = Object.fromEntries(Object.entries(choice.overrides).filter(([, value]) => value && Object.keys(value).length)); + return { preset: choice.preset, accent: choice.accent, ...(Object.keys(overrides).length ? { overrides } : {}), ...(choice.themes.length ? { themes: choice.themes } : {}) }; +} diff --git a/packages/runtime/src/themeRuntime.ts b/packages/runtime/src/themeRuntime.ts new file mode 100644 index 0000000..8f07975 --- /dev/null +++ b/packages/runtime/src/themeRuntime.ts @@ -0,0 +1,243 @@ +// The theme engine in a site's page: keeps one `