fix(desktop): add legacy engine startup compatibility notice

This commit is contained in:
zipg authored and GitHub committed 2026-09-29 12:23:56 +08:00
1 parent cf78eebbc9
commit ff7d817603
8 files changed
+869 -4

No files matched your search

+403
View File
@@ -125,6 +125,409 @@
<span>Loading…</span>
</div>
</div>
<script data-dbx-compat-probe>
// Reports engines that cannot render the app shell and, when one is detected, shows a
// notice built only from inline styles. This has to keep working on an engine whose
// entire `@layer` output is discarded, so it must never depend on Tailwind, design
// tokens, media queries, `:has()`, `oklch()`, `color-mix()`, `min()` or `focus-visible`.
//
// The probe cluster is exactly Tailwind v4's browser baseline, which is also the oldest
// engine the shell is styled for:
// @layer -> Safari 15.4, Chrome 99
// oklch() -> Safari 15.4, Chrome 111
// color-mix() -> Safari 16.2, Chrome 111
// media query range syntax -> Safari 16.4, Chrome 104
// Every probe fails open: a detection bug must never hide a working app behind a notice.
(() => {
const BYPASS_KEY = "dbx-compat-bypass";
const BANNER_KEY = "dbx-compat-banner-dismissed";
const FATAL_PROBES = [
["layer", () => supportsLayer()],
["oklch", () => supportsStyle("color", "oklch(0.5 0.1 180)")],
["color-mix", () => supportsStyle("color", "color-mix(in oklab, black 10%, transparent)")],
];
// Degraded: the shell renders, but responsive variants and focus rings are incomplete.
const DEGRADED_PROBES = [
["media-query-range", () => supportsMediaQueryRange()],
["has-selector", () => supportsSelector(":has(*)")],
["focus-visible", () => supportsSelector(":focus-visible")],
];
const FEATURE_LABELS = {
layer: "@layer",
oklch: "oklch()",
"color-mix": "color-mix()",
"media-query-range": "media query range syntax",
"has-selector": ":has()",
"focus-visible": ":focus-visible",
};
const TEXT = {
"zh-CN": {
listSeparator: "、",
macTitle: "当前系统的 WebKit 版本过旧,DBX 界面无法正常显示",
macBody: "DBX 的界面由 macOS 内置的 WebKit 渲染,而这台 Mac 上的 WebKit 版本过旧,缺少 DBX 需要的 CSS 特性,界面会显示异常。",
macSteps: [
"打开「系统设置 → 通用 → 软件更新」,把 macOS 升级到 Monterey 的最新版本(12.7.6)。",
"在同一页面把 Safari 升级到最新版(Monterey 最高支持 Safari 17.6)。",
"完全退出 DBX,然后重新打开。",
],
macNote: "升级 Safari 会同时更新系统 WebKit,DBX 不需要重新安装。",
webTitle: "当前浏览器版本过旧,DBX 界面无法正常显示",
webBody: "检测到 {engine},该版本过旧,缺少 DBX 需要的 CSS 特性,界面会显示异常。",
webSteps: [
"请把浏览器升级到最新版本(Chrome、Edge、Firefox、Safari 均可)。",
"升级完成后重新打开 DBX。",
],
desktopSteps: [
"请把操作系统升级到最新版本,以便同步更新系统内置的 WebView。",
"完全退出 DBX,然后重新打开。",
],
webNote: "如果浏览器由公司统一分发、无法自行升级,请联系 IT 部门。",
macBanner: "检测到 {engine},部分样式可能显示异常。请在「系统设置 → 通用 → 软件更新」把 Safari 升级到最新版,再重新打开 DBX。",
desktopBanner: "检测到 {engine},部分样式可能显示异常。建议升级操作系统以更新系统内置的 WebView,再重新打开 DBX。",
webBanner: "检测到 {engine},部分样式可能显示异常。建议把浏览器升级到最新版本,再重新打开。",
continue: "仍然继续(界面会显示异常)",
dismiss: "知道了",
detected: "检测结果",
},
"zh-TW": {
listSeparator: "、",
macTitle: "目前系統的 WebKit 版本過舊,DBX 介面無法正常顯示",
macBody: "DBX 的介面由 macOS 內建的 WebKit 算繪,而這台 Mac 上的 WebKit 版本過舊,缺少 DBX 需要的 CSS 特性,介面會顯示異常。",
macSteps: [
"打開「系統設定 → 一般 → 軟體更新」,把 macOS 更新到 Monterey 的最新版本(12.7.6)。",
"在同一頁面把 Safari 更新到最新版(Monterey 最高支援 Safari 17.6)。",
"完整結束 DBX,然後重新打開。",
],
macNote: "更新 Safari 會同時更新系統 WebKit,DBX 不需要重新安裝。",
webTitle: "目前瀏覽器版本過舊,DBX 介面無法正常顯示",
webBody: "偵測到 {engine},該版本過舊,缺少 DBX 需要的 CSS 特性,介面會顯示異常。",
webSteps: [
"請把瀏覽器更新到最新版本(Chrome、Edge、Firefox、Safari 皆可)。",
"更新完成後重新打開 DBX。",
],
desktopSteps: [
"請把作業系統更新到最新版本,以便同步更新系統內建的 WebView。",
"完整結束 DBX,然後重新打開。",
],
webNote: "如果瀏覽器由公司統一派送、無法自行更新,請聯絡 IT 部門。",
macBanner: "偵測到 {engine},部分樣式可能顯示異常。請在「系統設定 → 一般 → 軟體更新」把 Safari 更新到最新版,再重新打開 DBX。",
desktopBanner: "偵測到 {engine},部分樣式可能顯示異常。建議更新作業系統以更新系統內建的 WebView,再重新打開 DBX。",
webBanner: "偵測到 {engine},部分樣式可能顯示異常。建議把瀏覽器更新到最新版本,再重新打開。",
continue: "仍然繼續(介面會顯示異常)",
dismiss: "知道了",
detected: "偵測結果",
},
en: {
listSeparator: ", ",
macTitle: "This Mac's WebKit is too old for DBX to render correctly",
macBody: "DBX renders its UI with the WebKit built into macOS, and the WebKit on this Mac is too old: it is missing CSS features DBX relies on, so the UI renders incorrectly.",
macSteps: [
"Open System Settings → General → Software Update and update macOS to the latest Monterey release (12.7.6).",
"Update Safari to the latest version from the same panel (Monterey supports up to Safari 17.6).",
"Quit DBX completely, then open it again.",
],
macNote: "Updating Safari also updates the system WebKit, so DBX does not need to be reinstalled.",
webTitle: "This browser is too old for DBX to render correctly",
webBody: "Detected {engine}, which is too old: it is missing CSS features DBX relies on, so the UI renders incorrectly.",
webSteps: [
"Update your browser to the latest version (any modern Chrome, Edge, Firefox or Safari works).",
"Reopen DBX once the update is done.",
],
desktopSteps: [
"Update your operating system to the latest version so the built-in WebView is updated too.",
"Quit DBX completely, then open it again.",
],
webNote: "If your browser is managed by your company and cannot be updated, please contact IT.",
macBanner: "Detected {engine}. Some styles may render incorrectly - update Safari from System Settings > General > Software Update, then reopen DBX.",
desktopBanner: "Detected {engine}. Some styles may render incorrectly - update your operating system so its built-in WebView is updated, then reopen DBX.",
webBanner: "Detected {engine}. Some styles may render incorrectly - update your browser to the latest version, then reopen.",
continue: "Continue anyway (the UI will look wrong)",
dismiss: "Got it",
detected: "Detected",
},
};
const report = { tier: "ok", missing: [], engine: "", platform: "web", desktop: false, bypassed: false };
window.__DBX_WEBVIEW_COMPAT__ = report;
const el = (tag, css, text) => {
const node = document.createElement(tag);
if (css) node.style.cssText = css;
if (text !== undefined) node.textContent = text;
return node;
};
const storage = (store, key, value) => {
try {
if (value === undefined) return String(window[store].getItem(key) || "");
window[store].setItem(key, value);
} catch {
return "";
}
return "";
};
function supportsStyle(property, value) {
try {
return typeof CSS !== "undefined" && typeof CSS.supports === "function" && CSS.supports(property, value);
} catch {
return true;
}
}
function supportsSelector(selector) {
try {
return typeof CSS !== "undefined" && typeof CSS.supports === "function" && CSS.supports("selector(" + selector + ")");
} catch {
return true;
}
}
function supportsMediaQueryRange() {
try {
return typeof window.matchMedia === "function" && window.matchMedia("(width >= 0px)").matches;
} catch {
return true;
}
}
// `@layer` has no `CSS.supports()` form, so load a layered rule and read the custom
// property back: engines without cascade layers discard the whole block.
function supportsLayer() {
let style;
try {
style = document.createElement("style");
style.textContent = "@layer dbx-layer-probe{html{--dbx-layer-probe:1}}";
(document.head || document.documentElement).appendChild(style);
const value = window.getComputedStyle(document.documentElement).getPropertyValue("--dbx-layer-probe");
return String(value).trim() === "1";
} catch {
return true;
} finally {
if (style && style.parentNode) style.parentNode.removeChild(style);
}
}
function describeEngine(ua) {
const match =
/Edg\/(\d+)/.exec(ua) ||
/OPR\/(\d+)/.exec(ua) ||
/Firefox\/(\d+)/.exec(ua) ||
/Chrome\/(\d+)/.exec(ua) ||
/Version\/([\d.]+).*Safari/.exec(ua);
if (!match) return "";
const name = /Edg\//.test(ua)
? "Edge"
: /OPR\//.test(ua)
? "Opera"
: /Firefox\//.test(ua)
? "Firefox"
: /Chrome\//.test(ua)
? "Chrome"
: "Safari";
return name + " " + match[1];
}
function describePlatform() {
const platform = navigator.platform || "";
const ua = navigator.userAgent || "";
if (/Mac|iPhone|iPad|iPod/.test(platform) || /Mac OS X/.test(ua)) return "macos";
if (/Win/.test(platform) || /Windows/.test(ua)) return "windows";
if (/Linux|X11/.test(platform) || /Linux/.test(ua)) return "linux";
return "web";
}
function pickLanguage() {
const languages = navigator.languages && navigator.languages.length ? navigator.languages : [navigator.language || ""];
for (const language of languages) {
const tag = String(language).toLowerCase();
if (tag.indexOf("zh") === 0) return /hant|tw|hk|mo/.test(tag) ? "zh-TW" : "zh-CN";
if (tag.indexOf("en") === 0) return "en";
}
return "en";
}
function format(template, values) {
return String(template).replace(/\{(\w+)\}/g, (match, key) => (key in values ? values[key] : match));
}
function featureList(names, separator) {
return names.map((name) => FEATURE_LABELS[name] || name).join(separator);
}
function palette() {
const dark = document.documentElement.classList.contains("dark");
return {
background: dark ? "#131416" : "#ffffff",
text: dark ? "#f3f4f6" : "#111827",
muted: dark ? "#9ca3af" : "#4b5563",
subtle: dark ? "#6b7280" : "#6b7280",
border: dark ? "#2f3136" : "#e5e7eb",
surface: dark ? "#1b1d21" : "#f9fafb",
};
}
function renderNotice(tier, copy, names) {
const color = palette();
const banner = tier === "degraded";
const mac = report.desktop && report.platform === "macos";
const engine = report.engine || (report.desktop ? report.platform : "unknown");
const values = { engine: engine, features: featureList(names, copy.listSeparator) };
const steps = mac ? copy.macSteps : report.desktop ? copy.desktopSteps : copy.webSteps;
// The degraded banner names the exact thing to upgrade, so "update it" can never be
// read as "update DBX" or "update macOS".
const bannerText = mac ? copy.macBanner : report.desktop ? copy.desktopBanner : copy.webBanner;
const detail = copy.detected + ": " + (engine || "-") + (names.length ? " / " + values.features : "");
const surface = el(
"div",
[
"box-sizing:border-box;z-index:2147483647;text-align:left;",
"background:" + color.background + ";color:" + color.text + ";",
"font-family:system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;",
"font-size:13px;line-height:1.6;",
banner
? "position:fixed;left:50%;transform:translateX(-50%);bottom:16px;width:calc(100vw - 32px);max-width:520px;" +
"border:1px solid " + color.border + ";border-radius:10px;padding:12px 14px;box-shadow:0 8px 24px rgba(0,0,0,0.14);"
: "position:fixed;top:0;left:0;right:0;bottom:0;display:flex;overflow:auto;padding:24px;",
].join(""),
);
surface.setAttribute(banner ? "data-dbx-compat-banner" : "data-dbx-compat-gate", tier);
const card = banner
? surface
: el(
"div",
"margin:auto;max-width:620px;width:100%;box-sizing:border-box;border:1px solid " +
color.border +
";border-radius:12px;padding:22px;background:" +
color.background +
";",
);
if (!banner) {
card.appendChild(
el("div", "font-size:11px;font-weight:600;letter-spacing:0.08em;text-transform:uppercase;color:" + color.subtle + ";margin-bottom:10px;", "DBX"),
);
card.appendChild(el("h1", "margin:0 0 10px;font-size:17px;font-weight:600;line-height:1.4;", mac ? copy.macTitle : copy.webTitle));
}
card.appendChild(
el("p", "margin:0 0 12px;color:" + color.muted + ";", banner ? format(bannerText, values) : format(mac ? copy.macBody : copy.webBody, values)),
);
if (!banner) {
const list = el("ol", "margin:0 0 12px;padding-left:20px;");
for (const step of steps) {
list.appendChild(el("li", "margin:0 0 6px;", step));
}
card.appendChild(list);
card.appendChild(el("p", "margin:0 0 14px;font-size:12px;color:" + color.subtle + ";", mac ? copy.macNote : copy.webNote));
}
const footer = el("div", "display:flex;flex-wrap:wrap;align-items:center;gap:10px;");
if (!banner) {
footer.appendChild(
el(
"span",
"font-size:11px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;color:" +
color.subtle +
";background:" +
color.surface +
";border-radius:6px;padding:4px 8px;overflow-wrap:anywhere;",
detail,
),
);
}
const dismiss = el(
"button",
"font:inherit;font-size:12px;cursor:pointer;border:1px solid " +
color.border +
";border-radius:6px;background:transparent;color:" +
color.text +
";padding:6px 12px;",
banner ? copy.dismiss : copy.continue,
);
dismiss.setAttribute("type", "button");
dismiss.setAttribute("data-dbx-compat-dismiss", "");
dismiss.addEventListener("click", () => {
if (banner) {
storage("localStorage", BANNER_KEY, "1");
surface.remove();
return;
}
storage("sessionStorage", BYPASS_KEY, "1");
window.location.reload();
});
footer.appendChild(dismiss);
card.appendChild(footer);
if (!banner) surface.appendChild(card);
document.body.appendChild(surface);
}
try {
report.desktop = Boolean(window.__TAURI_INTERNALS__ || window.__TAURI__);
report.platform = describePlatform();
report.engine = describeEngine(navigator.userAgent || "");
const missingFatal = FATAL_PROBES.filter((probe) => !probe[1]()).map((probe) => probe[0]);
const missingDegraded = DEGRADED_PROBES.filter((probe) => !probe[1]()).map((probe) => probe[0]);
report.missing = missingFatal.concat(missingDegraded);
// Only a missing @layer discards the stylesheet wholesale. Without @layer's
// fallback engine the shell cannot render at all (fatal); with @layer working,
// missing color functions only drop color declarations, so the shell still
// renders and the notice degrades to the dismissible banner. This also keeps
// builds that ship a fixed Chromium-109-based webview out of the blocking tier.
const missingColors = missingFatal.filter((name) => name !== "layer");
report.tier = missingFatal.includes("layer")
? "fatal"
: missingColors.length || missingDegraded.length
? "degraded"
: "ok";
let override = null;
try {
override = new URLSearchParams(window.location.search).get("dbx-compat");
} catch {
override = null;
}
const forced = override === "force" || override === "fatal" || override === "force-degraded" || override === "degraded";
if (override === "reset") storage("sessionStorage", BYPASS_KEY, "");
if (override === "off") {
report.tier = "ok";
report.missing = [];
} else if (override === "force" || override === "fatal") {
report.tier = "fatal";
report.missing = ["layer"];
} else if (override === "force-degraded" || override === "degraded") {
report.tier = "degraded";
report.missing = ["media-query-range"];
}
report.bypassed = !forced && storage("sessionStorage", BYPASS_KEY) === "1";
// Recorded for support and for automated checks, independently of the notice.
document.documentElement.setAttribute("data-dbx-compat", report.tier);
// Dismissing the banner is a per-device decision about an advisory notice. It must not
// silence the blocking gate, which is re-asked every session on purpose: a shell whose
// stylesheet is dropped renders as an unusable UI, and users need to know why.
const dismissedDegraded = report.tier === "degraded" && storage("localStorage", BANNER_KEY) === "1";
if (report.tier !== "ok" && !report.bypassed && !dismissedDegraded) {
renderNotice(report.tier, TEXT[pickLanguage()] || TEXT.en, report.missing);
}
} catch (error) {
// Fail open: never hide a working app because the probe itself misbehaved.
report.tier = "ok";
report.missing = [];
try {
console.warn("[COMPAT] engine probe failed", error);
} catch {
/* console is unavailable */
}
}
})();
</script>
<script type="module" src="/src/main.ts"></script>
</body>
</html>
@@ -0,0 +1,271 @@
// The notice is the only thing a user with an unusable shell ever sees, so its behaviour matters
// as much as its copy: which engines gate, which only get a banner, how often each comes back,
// and that dismissing one can never silence the other. These tests run the real inline script from
// index.html against stubbed engine capabilities instead of asserting on its source text.
import { readFileSync } from "node:fs";
import vm from "node:vm";
import { describe, expect, it } from "vitest";
const indexHtml = readFileSync(new URL("../../index.html", import.meta.url), "utf8");
const openTag = indexHtml.indexOf("<script data-dbx-compat-probe>");
const PROBE_SOURCE = indexHtml.slice(indexHtml.indexOf(">", openTag) + 1, indexHtml.indexOf("</script>", openTag));
const SAFARI_15_2_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.2 Safari/605.1.15";
const SAFARI_16_2_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.2 Safari/605.1.15";
const CHROME_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
const WINDOWS_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
type Capabilities = {
layer: boolean;
oklch: boolean;
colorMix: boolean;
mediaRange: boolean;
has: boolean;
focusVisible: boolean;
};
// Capability sets of the engines this notice exists for.
const SAFARI_15_2: Capabilities = { layer: false, oklch: false, colorMix: false, mediaRange: false, has: false, focusVisible: false };
const SAFARI_16_2: Capabilities = { layer: true, oklch: true, colorMix: true, mediaRange: false, has: true, focusVisible: true };
// Chromium 109: the last engine some fixed-runtime desktop builds can ever ship.
const CHROMIUM_109: Capabilities = { layer: true, oklch: false, colorMix: false, mediaRange: true, has: true, focusVisible: true };
const CHROME_120: Capabilities = { layer: true, oklch: true, colorMix: true, mediaRange: true, has: true, focusVisible: true };
class FakeElement {
tagName: string;
style: Record<string, string> = {};
textContent = "";
parentNode: FakeElement | null = null;
children: FakeElement[] = [];
attributes: Record<string, string> = {};
classList = { contains: () => false, add: () => {}, remove: () => {}, toggle: () => false };
constructor(tagName: string) {
this.tagName = tagName;
}
appendChild(node: FakeElement): FakeElement {
node.parentNode = this;
this.children.push(node);
return node;
}
removeChild(node: FakeElement): FakeElement {
const index = this.children.indexOf(node);
if (index >= 0) this.children.splice(index, 1);
node.parentNode = null;
return node;
}
remove(): void {
this.parentNode?.removeChild(this);
}
setAttribute(name: string, value: string): void {
this.attributes[name] = String(value);
}
getAttribute(name: string): string | null {
return name in this.attributes ? this.attributes[name] : null;
}
removeAttribute(name: string): void {
delete this.attributes[name];
}
addEventListener(): void {}
removeEventListener(): void {}
}
function textOf(node: FakeElement): string {
return [node.textContent, ...node.children.map(textOf)].join(" ");
}
function storageStub(initial: Record<string, string> = {}) {
const values: Record<string, string> = { ...initial };
return {
values,
getItem: (key: string) => (key in values ? values[key] : null),
setItem: (key: string, value: string) => {
values[key] = String(value);
},
};
}
type ProbeOptions = {
capabilities: Capabilities;
userAgent: string;
desktop?: boolean;
session?: Record<string, string>;
local?: Record<string, string>;
search?: string;
platform?: string;
};
function runProbe(options: ProbeOptions) {
const documentElement = new FakeElement("html");
const head = new FakeElement("head");
const body = new FakeElement("body");
const session = storageStub(options.session);
const local = storageStub(options.local);
const windowStub: Record<string, unknown> = {
location: { search: options.search ?? "", reload: () => {} },
sessionStorage: session,
localStorage: local,
matchMedia: (query: string) => ({
matches: options.capabilities.mediaRange && /[<>]=?/.test(query),
media: query,
addEventListener: () => {},
removeEventListener: () => {},
}),
getComputedStyle: () => ({
getPropertyValue: (name: string) => (name === "--dbx-layer-probe" && options.capabilities.layer ? "1" : ""),
}),
addEventListener: () => {},
dispatchEvent: () => {},
};
if (options.desktop) windowStub.__TAURI_INTERNALS__ = {};
const context = vm.createContext({
window: windowStub,
document: {
documentElement,
head,
body,
createElement: (tag: string) => new FakeElement(tag),
querySelector: () => null,
getElementById: () => null,
addEventListener: () => {},
},
navigator: {
userAgent: options.userAgent,
platform: options.platform ?? "MacIntel",
languages: ["zh-CN"],
language: "zh-CN",
},
CSS: {
supports: (first: string, second?: string) => {
if (second === undefined) {
const condition = String(first);
if (condition.includes("selector(:has")) return options.capabilities.has;
if (condition.includes("selector(:focus-visible")) return options.capabilities.focusVisible;
return true;
}
const value = String(second);
if (value.includes("oklch")) return options.capabilities.oklch;
if (value.includes("color-mix")) return options.capabilities.colorMix;
return true;
},
},
console: { warn: () => {}, log: () => {} },
URLSearchParams,
});
vm.runInContext(PROBE_SOURCE, context, { filename: "index.html#dbx-compat-probe" });
const report = windowStub.__DBX_WEBVIEW_COMPAT__ as {
tier: string;
missing: string[];
engine: string;
bypassed: boolean;
};
const notices = body.children.filter((child) => "data-dbx-compat-gate" in child.attributes || "data-dbx-compat-banner" in child.attributes);
return {
tier: report.tier,
missing: report.missing,
engine: report.engine,
bypassed: report.bypassed,
recorded: documentElement.attributes["data-dbx-compat"] ?? null,
notice: notices.length === 0 ? "none" : "data-dbx-compat-gate" in notices[0].attributes ? "gate" : "banner",
noticeText: notices.length === 0 ? "" : textOf(notices[0]),
session: session.values,
local: local.values,
};
}
describe("engine compatibility notice rendering", () => {
it("gates an engine whose whole layered stylesheet would be dropped", () => {
const result = runProbe({ capabilities: SAFARI_15_2, userAgent: SAFARI_15_2_UA, desktop: true });
expect(result.tier).toBe("fatal");
expect(result.notice).toBe("gate");
expect(result.recorded).toBe("fatal");
expect(result.missing).toEqual(["layer", "oklch", "color-mix", "media-query-range", "has-selector", "focus-visible"]);
expect(result.noticeText).toContain("12.7.6");
expect(result.noticeText).toContain("Safari 17.6");
});
it("only banners an engine that still renders the shell", () => {
const result = runProbe({ capabilities: SAFARI_16_2, userAgent: SAFARI_16_2_UA });
expect(result.tier).toBe("degraded");
expect(result.notice).toBe("banner");
expect(result.missing).toEqual(["media-query-range"]);
});
it("banners instead of gating a fixed Chromium-109 webview that lacks the color functions", () => {
// @layer works, so the stylesheet is not dropped wholesale — only color
// declarations are. Blocking every launch of such a build would be
// un-actionable: the runtime is fixed and can never be updated.
const result = runProbe({ capabilities: CHROMIUM_109, userAgent: WINDOWS_UA, desktop: true });
expect(result.tier).toBe("degraded");
expect(result.notice).toBe("banner");
expect(result.missing).toEqual(["oklch", "color-mix"]);
});
it("names exactly what to upgrade instead of a bare 'update it'", () => {
const mac = runProbe({ capabilities: SAFARI_16_2, userAgent: SAFARI_16_2_UA, desktop: true });
expect(mac.noticeText).toContain("把 Safari 升级到最新版");
const web = runProbe({ capabilities: SAFARI_16_2, userAgent: SAFARI_16_2_UA });
expect(web.noticeText).toContain("把浏览器升级到最新版本");
// Windows/Linux desktop clients ship their own WebView, so the fix is the operating system.
const windowsDesktop = runProbe({
capabilities: SAFARI_16_2,
userAgent: WINDOWS_UA,
platform: "Win32",
desktop: true,
});
expect(windowsDesktop.noticeText).toContain("升级操作系统以更新系统内置的 WebView");
expect(windowsDesktop.noticeText).not.toContain("Safari");
});
it("re-asks the gate every session but remembers a dismissed banner", () => {
expect(runProbe({ capabilities: SAFARI_15_2, userAgent: SAFARI_15_2_UA, desktop: true }).notice).toBe("gate");
expect(runProbe({ capabilities: SAFARI_15_2, userAgent: SAFARI_15_2_UA, desktop: true, session: {} }).notice).toBe("gate");
const bypassed = runProbe({ capabilities: SAFARI_15_2, userAgent: SAFARI_15_2_UA, desktop: true, session: { "dbx-compat-bypass": "1" } });
expect(bypassed.notice).toBe("none");
expect(bypassed.tier).toBe("fatal");
expect(bypassed.bypassed).toBe(true);
const dismissed = runProbe({ capabilities: SAFARI_16_2, userAgent: SAFARI_16_2_UA, local: { "dbx-compat-banner-dismissed": "1" } });
expect(dismissed.notice).toBe("none");
expect(dismissed.tier).toBe("degraded");
});
it("never lets a dismissed banner silence the blocking gate", () => {
const result = runProbe({
capabilities: SAFARI_15_2,
userAgent: SAFARI_15_2_UA,
desktop: true,
local: { "dbx-compat-banner-dismissed": "1" },
});
expect(result.tier).toBe("fatal");
expect(result.notice).toBe("gate");
});
it("stays out of the way on an engine that renders the shell", () => {
const result = runProbe({ capabilities: CHROME_120, userAgent: CHROME_UA, desktop: true });
expect(result.tier).toBe("ok");
expect(result.notice).toBe("none");
expect(result.recorded).toBe("ok");
});
it("fails open when the probe itself throws", () => {
const result = runProbe({ capabilities: CHROME_120, userAgent: CHROME_UA, search: "?dbx-compat=reset" });
expect(result.tier).toBe("ok");
expect(result.notice).toBe("none");
});
});
+87
View File
@@ -0,0 +1,87 @@
// The compatibility notice in index.html has to render on engines whose entire `@layer` output
// is discarded, so its styling and its probe order are load-bearing and easy to break by
// accident. These assertions pin the parts a browser test cannot: that the notice runs before
// the bundle, that it never depends on anything the broken engine would drop, and that the copy
// still tells each kind of user how to fix it.
import { readFileSync } from "node:fs";
import { describe, expect, it } from "vitest";
const indexHtml = readFileSync(new URL("../../index.html", import.meta.url), "utf8");
function probeScriptSource(): string {
const start = indexHtml.indexOf("<script data-dbx-compat-probe>");
expect(start).toBeGreaterThan(-1);
return indexHtml.slice(start, indexHtml.indexOf("</script>", start));
}
describe("engine compatibility notice", () => {
const script = probeScriptSource();
it("runs before the app bundle so a broken shell is never painted first", () => {
expect(indexHtml.indexOf("data-dbx-compat-probe")).toBeLessThan(indexHtml.indexOf('src="/src/main.ts"'));
});
it("styles the notice with inline styles only", () => {
// `@layer` blocks are dropped wholesale by the engines this notice targets, and the design
// tokens live in `@layer theme`. Production CSS also rewrites `min-width` media queries into
// range syntax those engines cannot parse. Inline styles avoid all three hazards.
expect(script).toContain("style.cssText");
expect(script).not.toContain("var(--");
expect(script).not.toContain("@media");
});
it("probes every capability the layered stylesheet depends on", () => {
for (const probe of ["layer", "oklch", "color-mix", "media-query-range", "has-selector", "focus-visible"]) {
expect(script).toContain(`["${probe}"`);
}
});
it("separates a blocking failure from a degraded one", () => {
expect(script).toContain("FATAL_PROBES");
expect(script).toContain("DEGRADED_PROBES");
// Only a missing @layer discards the stylesheet wholesale; engines that keep
// @layer but lack the color functions still render and get the banner tier.
// This keeps fixed Chromium-109-based webview builds below the blocking gate.
expect(script).toContain('missingFatal.includes("layer")');
expect(script).toContain('const missingColors = missingFatal.filter((name) => name !== "layer");');
expect(script).toContain("missingColors.length || missingDegraded.length");
});
it("fails open when the probe itself throws", () => {
expect(script).toContain("catch (error)");
expect(script).toContain('report.tier = "ok";');
});
it("publishes the verdict for the bundle and for support", () => {
expect(script).toContain("window.__DBX_WEBVIEW_COMPAT__ = report");
expect(script).toContain('"dbx-compat"');
expect(script).toContain("dbx-compat-bypass");
});
it("routes each audience to the upgrade that actually fixes it", () => {
// Desktop users cannot update a browser, and browser users cannot update WebKit.
expect(script).toContain("12.7.6");
expect(script).toContain("Safari 17.6");
expect(script).toContain("Chrome、Edge、Firefox、Safari");
expect(script).toContain("Update your browser to the latest version");
});
it("names the thing to upgrade in the degraded banner", () => {
// "建议升级后使用" was ambiguous: upgrade DBX, macOS, or Safari?
expect(script).not.toContain("建议升级后使用");
for (const key of ["macBanner", "desktopBanner", "webBanner"]) {
// Every language carries its own copy, and the picker chooses between them.
expect(script.split(key + ":").length - 1).toBe(3);
}
expect(script).toContain("const bannerText = mac ? copy.macBanner : report.desktop ? copy.desktopBanner : copy.webBanner;");
});
it("records the verdict for support and keeps the two notices independent", () => {
expect(script).toContain('document.documentElement.setAttribute("data-dbx-compat", report.tier)');
expect(script).toContain('report.tier !== "ok" && !report.bypassed');
// Dismissing the advisory banner must not silence the blocking gate.
expect(script).toContain('const dismissedDegraded = report.tier === "degraded" && storage("localStorage", BANNER_KEY) === "1"');
expect(script).toContain("!report.bypassed && !dismissedDegraded");
});
});
+6 -1
View File
@@ -33,6 +33,11 @@ describe("startup input guard", () => {
it("installs before the application module and is released after mount", () => {
expect(indexSource.indexOf("data-dbx-startup-input-guard")).toBeLessThan(indexSource.indexOf('src="/src/main.ts"'));
expect(mainSource.indexOf('app.mount("#root")')).toBeLessThan(mainSource.indexOf('window.dispatchEvent(new Event("dbx:startup-ready"))'));
// The engine-compatibility gate releases the guard earlier on the blocked path, so search
// for the release that belongs to mounting instead of the first one in the file.
const mountIndex = mainSource.indexOf('app.mount("#root")');
expect(mountIndex).toBeGreaterThan(-1);
expect(mainSource.indexOf('window.dispatchEvent(new Event("dbx:startup-ready"))', mountIndex)).toBeGreaterThan(mountIndex);
});
});
@@ -1,4 +1,4 @@
export type StartupPhase = "bootstrap" | "gate-mounted" | "locale-ready" | "auth-ready" | "migration-ready" | "app-mounted" | "settings-ready" | "connections-ready" | "tabs-restored";
export type StartupPhase = "bootstrap" | "compat-blocked" | "gate-mounted" | "locale-ready" | "auth-ready" | "migration-ready" | "app-mounted" | "settings-ready" | "connections-ready" | "tabs-restored";
export function markStartupPhase(phase: StartupPhase): void {
const name = `dbx:startup:${phase}`;
+47 -1
View File
@@ -1,7 +1,7 @@
// @vitest-environment happy-dom
import { afterEach, describe, expect, it, vi } from "vitest";
import { applyLegacyWebViewClass, isLegacyWebView, LEGACY_WEBVIEW_CLASS, missingLegacyWebViewCapabilities, supportsRegExpLookbehind } from "@/lib/ui/legacyWebView";
import { applyLegacyWebViewClass, isBlockingCompatFailure, isLegacyWebView, LEGACY_WEBVIEW_CLASS, missingLegacyWebViewCapabilities, supportsRegExpLookbehind, webViewCompatReport } from "@/lib/ui/legacyWebView";
const supportedFeatures = new Set(["oklch", "color-mix-oklab", "color-mix-oklch", "has-selector", "dynamic-viewport", "min-function", "media-query-range"]);
@@ -85,6 +85,52 @@ describe("legacy WebView detection", () => {
});
});
describe("inline engine probe report", () => {
const setReport = (report: unknown) => {
(window as unknown as Record<string, unknown>).__DBX_WEBVIEW_COMPAT__ = report;
};
afterEach(() => {
delete (window as unknown as Record<string, unknown>).__DBX_WEBVIEW_COMPAT__;
});
it("prefers the verdict the probe recorded before the bundle loaded", () => {
setReport({ tier: "fatal", missing: ["layer"], engine: "Safari 15.2", platform: "macos", desktop: true, bypassed: false });
expect(webViewCompatReport()?.engine).toBe("Safari 15.2");
expect(isLegacyWebView()).toBe(true);
expect(missingLegacyWebViewCapabilities()).toEqual(["layer"]);
});
it("treats a clean report as a supported engine", () => {
setReport({ tier: "ok", missing: [], engine: "Safari 17.6", platform: "macos", desktop: true, bypassed: false });
expect(isLegacyWebView()).toBe(false);
expect(missingLegacyWebViewCapabilities()).toEqual([]);
});
it("ignores a malformed report and falls back to probing", () => {
mockCssSupports(supportedFeatures);
setReport({ tier: "ok" });
expect(webViewCompatReport()).toBeUndefined();
expect(missingLegacyWebViewCapabilities()).toEqual([]);
});
it("blocks startup only on a fatal engine the user did not choose to continue past", () => {
expect(isBlockingCompatFailure()).toBe(false);
setReport({ tier: "degraded", missing: ["media-query-range"], engine: "", platform: "web", desktop: false, bypassed: false });
expect(isBlockingCompatFailure()).toBe(false);
setReport({ tier: "fatal", missing: ["layer"], engine: "", platform: "macos", desktop: true, bypassed: false });
expect(isBlockingCompatFailure()).toBe(true);
setReport({ tier: "fatal", missing: ["layer"], engine: "", platform: "macos", desktop: true, bypassed: true });
expect(isBlockingCompatFailure()).toBe(false);
});
});
describe("supportsRegExpLookbehind", () => {
it("reports support when the engine compiles lookbehind patterns", () => {
expect(supportsRegExpLookbehind()).toBe(true);
+43
View File
@@ -1,5 +1,28 @@
export const LEGACY_WEBVIEW_CLASS = "dbx-legacy-webview";
/**
* Verdict recorded by the inline probe in index.html, which runs before this bundle loads.
* Reading it keeps a single source of truth, so the "upgrade your engine" notice and the
* `dbx-legacy-webview` fallback layer can never disagree. Unlike the probes below, the inline
* one also covers `@layer`, which is what decides whether the shell can be styled at all.
*/
export type WebViewCompatTier = "ok" | "degraded" | "fatal";
export interface WebViewCompatReport {
tier: WebViewCompatTier;
missing: string[];
engine: string;
platform: string;
desktop: boolean;
bypassed: boolean;
}
declare global {
interface Window {
__DBX_WEBVIEW_COMPAT__?: WebViewCompatReport;
}
}
type CssSupportCheck = {
name: string;
property?: string;
@@ -39,10 +62,30 @@ function supports(check: CssSupportCheck): boolean {
}
}
export function webViewCompatReport(): WebViewCompatReport | undefined {
if (typeof window === "undefined") return undefined;
const report = window.__DBX_WEBVIEW_COMPAT__;
if (!report || typeof report.tier !== "string" || !Array.isArray(report.missing)) return undefined;
return report;
}
export function missingLegacyWebViewCapabilities(): string[] {
const report = webViewCompatReport();
if (report) return [...report.missing];
return MODERN_CSS_FEATURES.filter((feature) => !supports(feature)).map((feature) => feature.name);
}
/**
* True when the startup notice is blocking the app: the engine drops the whole layered
* stylesheet, so mounting the shell would replace a readable message with an unstyled UI.
* A user who chose "continue anyway" is not blocked again until the next session.
*/
export function isBlockingCompatFailure(): boolean {
const report = webViewCompatReport();
return report?.tier === "fatal" && report.bypassed !== true;
}
/**
* Old WebKit (Safari < 16.4) throws SyntaxError when compiling regular
* expressions with lookbehind or the named-group shapes Shiki's JavaScript
+11 -1
View File
@@ -4,7 +4,7 @@ import "./styles/globals.css";
import { installDebugLogCapture } from "@/lib/backend/debugLog";
import { retryStartupAfterPreloadFailure } from "@/lib/startup/startupPreloadRecovery";
import { markStartupPhase } from "@/lib/startup/startupTiming";
import { applyLegacyWebViewClass } from "@/lib/ui/legacyWebView";
import { applyLegacyWebViewClass, isBlockingCompatFailure } from "@/lib/ui/legacyWebView";
function startupErrorMessage(error: unknown): string {
if (error instanceof Error) {
@@ -77,6 +77,16 @@ function installGlobalInputAttrs() {
async function bootstrap() {
markStartupPhase("bootstrap");
console.log("[STARTUP] frontend bootstrap begin");
// The inline engine probe in index.html has already painted an upgrade notice when this
// engine cannot style the shell; mounting over it would only replace a readable message
// with an unstyled UI. The notice's own button reloads once the user opts to continue.
if (isBlockingCompatFailure()) {
markStartupPhase("compat-blocked");
console.warn("[STARTUP] blocked by engine compatibility notice");
window.dispatchEvent(new Event("dbx:startup-ready"));
return;
}
const [{ default: i18n, loadSavedLocale }, { default: App }] = await Promise.all([import("./i18n"), import("./StartupGate.vue")]);
console.log("[STARTUP] frontend modules loaded");
const localeReady = loadSavedLocale();