@nsnanocat/preference-panes 0.9.4 → 0.9.6

package/dist/module/host.mjs

@@ -0,0 +1,589 @@
+/**
+ * Bilibili common WebView 的官方 JSBridge 适配器。
+ * Official JSBridge adapter for Bilibili common WebViews.
+ */
+class BilibiliHost {
+    #bridge;
+    #select;
+    #state = { title: "", actions: [], busy: false };
+    #revision = 0;
+    #queue = Promise.resolve();
+    #destroyed = false;
+    #document;
+    #navigation = result => {
+        if (result.code !== 0 || result.data?.id !== "preference-panes.more" || this.#state.busy || this.#state.actions.length === 0) return;
+        const revision = this.#revision;
+        const actions = this.#state.actions;
+        this.#bridge
+            .useNative("liveUI.selectPanel", {
+                title: "更多操作",
+                options: actions.map(action => ({ text: action.label, value: action.id })),
+            })
+            .then(result => {
+                if (this.#destroyed || revision !== this.#revision || this.#state.busy) return;
+                const action = actions.find(item => item.id === result.data.text);
+                if (action) this.#select(action.id);
+            });
+    };
+    #theme = result => {
+        if (result.code === 0 && result.data?.theme) this.#applyTheme(result.data.theme);
+    };
+    #keyboard = result => {
+        if (result.code === 0 && typeof result.data?.status === "boolean") this.#document.documentElement.style.setProperty("--pp-keyboard-height", `${result.data.status ? result.data.height : 0}px`);
+    };
+
+    /**
+     * 连接页面已加载的官方 SDK。
+     * Connect to the official SDK already loaded by the document.
+     * @param {(id: string) => void} select 模块菜单回调 / Module action callback.
+     * @param {Window} [host] Bilibili WebView 窗口 / Bilibili WebView window.
+     */
+    constructor(select, host = window) {
+        this.#bridge = host.biliBridge;
+        this.#select = select;
+        this.#document = host.document;
+        this.#applyTheme(host.navigator.userAgent.includes("themeId/2") ? 2 : 1);
+        this.ready = this.#connect();
+    }
+
+    /**
+     * 初始化主题、键盘和原生导航通道。
+     * Initialize theme, keyboard and native navigation channels.
+     * @returns {Promise<void>} 初始化完成 / Initialization completion.
+     */
+    async #connect() {
+        await this.#bridge.initPromise;
+        if (!this.#bridge.isWbTypeCommon) throw new Error("PreferencePanes requires a Bilibili common WebView");
+        this.#bridge.addChannel("ui.observeThemeChange", this.#theme, { immediately: true });
+        this.#bridge.addChannel("ui.observeKeyboardStatus", this.#keyboard);
+        this.#bridge.addChannel("ui.observeNavigationClick", this.#navigation);
+        await this.#bridge.useNative("ui.setNavigationHide", { hide: false });
+    }
+
+    /**
+     * 同步官方导航标题和更多按钮。
+     * Synchronize the official navigation title and overflow button.
+     * @param {{title: string, actions: Array<{id: string, label: string}>, busy: boolean}} state 页面状态 / Page state.
+     * @returns {Promise<void>} 更新完成 / Update completion.
+     */
+    update(state) {
+        this.#state = state;
+        const revision = ++this.#revision;
+        const render = async () => {
+            await this.ready;
+            if (this.#destroyed || revision !== this.#revision) return;
+            await this.#bridge.useNative("ui.setTitle", { title: state.title });
+            if (this.#destroyed || revision !== this.#revision) return;
+            await this.#bridge.useNative("ui.setNavigationButton", {
+                buttons: !state.busy && state.actions.length ? [{ id: "preference-panes.more", type: 3, visible: true }] : [],
+            });
+        };
+        this.#queue = this.#queue.then(render, render);
+        return this.#queue;
+    }
+
+    /**
+     * 显示官方确认面板。
+     * Show the official confirmation panel.
+     * @param {string} message 确认内容 / Confirmation message.
+     * @returns {Promise<boolean>} 用户是否确认 / Whether the user confirmed.
+     */
+    async confirm(message) {
+        await this.ready;
+        return new Promise((resolve, reject) =>
+            this.#bridge.callNative({
+                method: "ability.alert",
+                data: { type: "confirm", title: this.#state.title, message, confirmButton: "确定", cancelButton: "取消" },
+                onConfirm: () => resolve(true),
+                onCancel: () => resolve(false),
+                onNeutral: () => resolve(false),
+                callback: result => {
+                    if (result instanceof Error || result === "error") reject(new Error("Native confirmation failed"));
+                },
+            }),
+        );
+    }
+
+    /**
+     * 显示官方短提示。
+     * Show an official short notice.
+     * @param {string} message 提示内容 / Notice message.
+     * @returns {Promise<void>} 提示已提交 / Notice dispatched.
+     */
+    async notice(message) {
+        await this.ready;
+        await this.#bridge.useNative("liveUI.toast", { type: "short", msg: message });
+    }
+
+    /**
+     * 释放官方事件通道。
+     * Release official event channels.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#destroyed = true;
+        this.#revision++;
+        this.#bridge.removeChannel("ui.observeThemeChange", this.#theme);
+        this.#bridge.removeChannel("ui.observeKeyboardStatus", this.#keyboard);
+        this.#bridge.removeChannel("ui.observeNavigationClick", this.#navigation);
+    }
+
+    /**
+     * 将官方主题值映射到页面主题标记。
+     * Map the official theme value to document theme markers.
+     * @param {number | string} value 官方主题值 / Official theme value.
+     * @returns {void} 无返回值 / No return value.
+     */
+    #applyTheme(value) {
+        const dark = value === 2 || value === "dark";
+        this.#document.documentElement.dataset.theme = dark ? "dark" : "light";
+        this.#document.documentElement.classList.toggle("bili_dark", dark);
+    }
+}
+
+/**
+ * 统一解析模块页的资源地址：Header 优先于查询参数，再使用模块约定。
+ * Resolve module resource locations: headers override query parameters and module conventions.
+ * @param {URL} url 已解析的页面请求地址 / Parsed page request URL.
+ * @param {Record<string, string | undefined>} [headers] 请求头，名称不区分大小写 / Case-insensitive request headers.
+ * @returns {{url: string, module: string, json: string, css: string}} 页面上下文与两个资源输入 / Page context and two resource inputs.
+ */
+function pageInputs(url, headers = {}) {
+    const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(url.pathname);
+    if (!match) throw new TypeError("Open a concrete module URL");
+    const module = match[1];
+    const values = Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+    const json = values["x-preferencepanes-json"] ?? url.searchParams.get("json") ?? `/configs/${module}`;
+    const css = values["x-preferencepanes-css"] ?? url.searchParams.get("css") ?? "";
+    if (!json.trim()) throw new TypeError("JSON resource URL is required");
+    return { url: url.href, module, json, css };
+}
+
+/**
+ * 模块文档容器：原始 HTML 不改写，请求上下文随 iframe 元素传递。
+ * Module document container: preserve HTML verbatim and carry request context on the iframe element.
+ */
+class ModuleFrame extends EventTarget {
+    #url;
+    #options;
+    #controller = new AbortController();
+    #abort = () => this.destroy();
+    #state;
+    #change = event => {
+        this.#state = { ...event.detail, actions: event.detail.actions ?? [] };
+        this.dispatchEvent(new Event("change"));
+    };
+    #confirmation = event => {
+        const request = new CustomEvent("confirm", { cancelable: true, detail: event.detail });
+        if (!this.dispatchEvent(request)) event.preventDefault();
+    };
+    #notice = event => {
+        const notice = new CustomEvent("notice", { cancelable: true, detail: event.detail });
+        if (!this.dispatchEvent(notice)) event.preventDefault();
+    };
+
+    /**
+     * 建立 iframe 与请求输入；调用方挂载 element 后调用 load。
+     * Create the iframe and request inputs; callers mount element and then call load.
+     * @param {string | URL} url 模块请求地址 / Module request URL.
+     * @param {RequestInit} [options] 原生请求头和取消信号 / Native headers and cancellation signal.
+     */
+    constructor(url, options = {}) {
+        super();
+        this.#url = new URL(url, document.baseURI);
+        this.#options = { ...options, headers: new Headers(options.headers) };
+        const inputs = pageInputs(this.#url, Object.fromEntries(this.#options.headers));
+        this.element = document.createElement("iframe");
+        this.element.title = `${inputs.module} 设置`;
+        this.element.dataset.preferencePanes = JSON.stringify(inputs);
+        this.element.addEventListener("preferencepanes:change", this.#change);
+        this.element.addEventListener("preferencepanes:confirm", this.#confirmation);
+        this.element.addEventListener("preferencepanes:notice", this.#notice);
+        this.#state = { title: inputs.module, module: inputs.module, busy: false, canGoBack: true, actions: [] };
+        options.signal?.addEventListener("abort", this.#abort, { once: true });
+    }
+
+    /**
+     * 当前模块导航状态。
+     * Current module navigation state.
+     */
+    get state() {
+        return { ...this.#state };
+    }
+
+    /**
+     * 获取原始 HTML；晚到响应在退出后不得重新挂载。
+     * Fetch unmodified HTML; a late response must not remount after departure.
+     * @returns {Promise<void>} HTML 已交给 iframe；表单状态通过 change 事件提供 / HTML assigned; form state is reported through change.
+     */
+    async load() {
+        if (this.#options.signal?.aborted) this.destroy();
+        const timer = setTimeout(() => this.#controller.abort(), 10000);
+        try {
+            const response = await fetch(this.#url, { cache: "no-store", credentials: "omit", ...this.#options, signal: this.#controller.signal });
+            if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
+            const html = await response.text();
+            this.#controller.signal.throwIfAborted();
+            this.element.srcdoc = html;
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+
+    /**
+     * 使用 iframe 的联合历史返回；写入期间不导航。
+     * Navigate joint iframe history back, except while a write is pending.
+     * @returns {void} 无返回值 / No return value.
+     */
+    back() {
+        if (!this.#state.busy && this.#state.canGoBack) this.element.contentWindow.history.back();
+    }
+
+    /**
+     * 向模块发送菜单操作，不让宿主访问内部 DOM 或存储客户端。
+     * Dispatch a menu action without host access to internal DOM or the storage client.
+     * @param {string} id 当前可用操作 / Available action identifier.
+     * @returns {void} 无返回值 / No return value.
+     */
+    perform(id) {
+        if (this.#state.busy || !this.#state.actions.some(action => action.id === id)) throw new Error("Action is not available");
+        this.element.dispatchEvent(new CustomEvent("preferencepanes:action", { detail: id }));
+    }
+
+    /**
+     * 取消加载与事件订阅；节点保留到 Navigation 的退出动画结束。
+     * Cancel loading and subscriptions; Navigation retains the node until its exit animation ends.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#controller.abort();
+        this.#options.signal?.removeEventListener("abort", this.#abort);
+        this.element.removeEventListener("preferencepanes:change", this.#change);
+        this.element.removeEventListener("preferencepanes:confirm", this.#confirmation);
+        this.element.removeEventListener("preferencepanes:notice", this.#notice);
+    }
+}
+
+/**
+ * 模块入口的固定状态行，只通过 HEAD 探测安装状态和业务版本。
+ * Fixed module status row, probing installation and business version with HEAD only.
+ */
+class ModuleStatus extends EventTarget {
+    #element;
+    #controller;
+    #state = { status: "checking", version: null };
+
+    /**
+     * 绑定调用方提供的状态行。
+     * Bind a caller-owned status row.
+     * @param {HTMLElement} element 状态文字容器 / Status text container.
+     */
+    constructor(element) {
+        super();
+        this.#element = element;
+        this.#render("checking");
+    }
+
+    /**
+     * 当前安装状态与业务版本。
+     * Current installation state and business version.
+     */
+    get state() {
+        return { ...this.#state };
+    }
+
+    /**
+     * 每次进入重新探测，取消旧请求并忽略其迟到结果。
+     * Reprobe on entry, cancelling old requests and ignoring late results.
+     * @param {string | URL} url 配置 Mock 地址 / Configuration Mock URL.
+     * @returns {Promise<void>} 探测完成 / Probe completion.
+     */
+    async check(url) {
+        this.#controller?.abort();
+        const controller = (this.#controller = new AbortController());
+        this.#render("checking");
+        const timer = setTimeout(() => controller.abort(), 3500);
+        try {
+            const response = await fetch(url, { method: "HEAD", cache: "no-store", credentials: "omit", signal: controller.signal });
+            if (controller !== this.#controller) return;
+            const version = response.headers.get("X-PreferencePanes-Version")?.trim() || null;
+            this.#render(response.status === 200 ? "installed" : "missing", version);
+        } catch {
+            if (controller === this.#controller) this.#render("missing");
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+
+    /**
+     * 更新状态标签，缺少版本时不伪造版本号。
+     * Render the label without inventing a missing version.
+     * @param {"checking" | "installed" | "missing"} status 状态 / State.
+     * @param {string | null} [version] 业务版本 / Business version.
+     * @returns {void} 无返回值 / No return value.
+     */
+    #render(status, version = null) {
+        this.#state = { status, version: status === "installed" ? version : null };
+        switch (status) {
+            case "checking":
+                this.#element.textContent = "检测中";
+                break;
+            case "installed":
+                this.#element.textContent = version ?? "版本未知";
+                break;
+            case "missing":
+                this.#element.textContent = "未安装";
+                break;
+        }
+        this.#element.dataset.state = status;
+        this.#element.title = this.#element.textContent;
+        this.dispatchEvent(new Event("change"));
+    }
+
+    /**
+     * 释放尚未完成的探测。
+     * Release pending probes.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#controller?.abort();
+        this.#controller = undefined;
+    }
+}
+
+/**
+ * 同一文档内的主页/子页导航；iframe 各自的实例通过浏览器联合历史协作。
+ * Navigate home/detail views within a document; iframe instances cooperate through joint browser history.
+ */
+class Navigation extends EventTarget {
+    #container;
+    #home;
+    #create;
+    #window;
+    #key = null;
+    #view;
+    #retiring;
+    #controller;
+    #animation;
+    #scroll = new WeakMap();
+    #onHistory = () => this.#route();
+    #onPageShow = event => {
+        if (event.persisted) this.#route(true);
+    };
+
+    /**
+     * 根视图始终保留；工厂按需提供子页，可用 signal 取消离开后的异步加载。
+     * Retain the home view and create details on demand; signal cancels async work after departure.
+     * @param {HTMLElement} container 由调用方布局的页面容器 / Caller-styled view container.
+     * @param {HTMLElement} home 已创建的主页节点 / Existing home view.
+     * @param {(key: string, signal: AbortSignal) => HTMLElement | undefined} create 子页工厂；未知路径返回 undefined / Detail factory; undefined for unknown routes.
+     */
+    constructor(container, home, create) {
+        super();
+        this.#container = container;
+        this.#home = home;
+        this.#create = create;
+        this.#window = container.ownerDocument.defaultView;
+        container.replaceChildren(home);
+        this.#window.addEventListener("popstate", this.#onHistory);
+        this.#window.addEventListener("hashchange", this.#onHistory);
+        this.#window.addEventListener("pageshow", this.#onPageShow);
+        this.#route();
+    }
+
+    /**
+     * 当前子页键；空字符串表示主页。
+     * Current detail key; empty means home.
+     */
+    get current() {
+        return this.#key;
+    }
+
+    /**
+     * 是否可以返回上一级或先前文档。
+     * Whether a parent view or previous document is available.
+     */
+    get canGoBack() {
+        return Boolean(this.#key) || this.#window.history.length > 1;
+    }
+
+    /**
+     * 加入子页历史；使用文档自身 URL，避免 srcdoc 按宿主 base URL 跳转。
+     * Push a detail using the document URL, avoiding srcdoc navigation against the host base URL.
+     * @param {string} key 子页键 / Detail key.
+     * @returns {void} 无返回值 / No return value.
+     */
+    open(key) {
+        if (key === this.#key) return;
+        const url = new URL(this.#window.location.href);
+        url.hash = encodeURIComponent(key);
+        this.#window.history.pushState({ ...this.#window.history.state, preferencePanesRoute: key }, "", url.href);
+        this.#route();
+    }
+
+    /**
+     * 沿浏览器联合历史返回，根页可退回宿主或上个文档。
+     * Go back through joint history, including a host or previous document from home.
+     * @returns {void} 无返回值 / No return value.
+     */
+    back() {
+        if (this.canGoBack) this.#window.history.back();
+    }
+
+    /**
+     * 解析 URL 并统一处理页面切换、加载取消与动画结束后的释放。
+     * Resolve the URL and coordinate transitions, cancellation and release after animation.
+     * @param {boolean} [reload] 从页面缓存恢复时重新创建子页 / Recreate a detail after bfcache restoration.
+     * @returns {void} 无返回值 / No return value.
+     */
+    #route(reload = false) {
+        const url = new URL(this.#window.location.href);
+        let key;
+        try {
+            key = decodeURIComponent(url.hash.slice(1));
+        } catch (error) {
+            if (!(error instanceof URIError)) throw error;
+            key = "";
+        }
+        if (!reload && key === this.#key) return;
+        this.#controller?.abort();
+        this.#controller = new AbortController();
+        const next = key ? this.#create(key, this.#controller.signal) : undefined;
+        if (!next) key = "";
+        const history = this.#window.history;
+        // 直接打开子页时建立一次主页历史；刷新不重复堆叠。
+        // Seed home history once for direct details, without stacking entries on reload.
+        if (url.hash && history.state?.preferencePanesRoute !== key) {
+            url.hash = "";
+            history.replaceState({ ...history.state, preferencePanesRoute: "" }, "", url.href);
+            if (key) {
+                url.hash = encodeURIComponent(key);
+                history.pushState({ ...history.state, preferencePanesRoute: key }, "", url.href);
+            }
+        }
+        const previous = this.#view;
+        const position = previous ? this.#window.getComputedStyle(previous).transform : "none";
+        this.#animation?.cancel();
+        this.#retiring?.remove();
+        this.#retiring = previous;
+        if (previous) {
+            this.#scroll.set(previous, previous.scrollTop);
+            previous.inert = true;
+        }
+        this.#key = key;
+        this.#view = next;
+        this.#home.inert = Boolean(next);
+        if (next) {
+            next.inert = false;
+            this.#container.append(next);
+            next.scrollTop = this.#scroll.get(next) ?? 0;
+        }
+        const moving = next ?? previous;
+        if (moving) {
+            const animation = moving.animate([{ transform: next ? "translateX(100%)" : position }, { transform: next ? "translateX(0)" : "translateX(100%)" }], { duration: this.#window.matchMedia("(prefers-reduced-motion: reduce)").matches ? 0 : 280, easing: "cubic-bezier(.22,.61,.36,1)", fill: "forwards" });
+            this.#animation = animation;
+            animation.onfinish = () => {
+                if (this.#animation !== animation) return;
+                this.#retiring?.remove();
+                this.#retiring = undefined;
+                animation.cancel();
+                this.#animation = undefined;
+            };
+        }
+        this.dispatchEvent(new Event("change"));
+    }
+
+    /**
+     * 释放监听器、加载、动画和节点；调用方可重新创建导航。
+     * Release listeners, loads, animations and nodes so callers can recreate navigation.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#window.removeEventListener("popstate", this.#onHistory);
+        this.#window.removeEventListener("hashchange", this.#onHistory);
+        this.#window.removeEventListener("pageshow", this.#onPageShow);
+        this.#controller?.abort();
+        this.#animation?.cancel();
+        this.#retiring?.remove();
+        this.#view?.remove();
+        this.#home.remove();
+    }
+}
+
+const container = document.querySelector("[data-preference-panes-pages]");
+const home = document.querySelector("[data-preference-panes-home]");
+const template = document.querySelector("template[data-preference-panes-module]");
+const buttons = [...home.querySelectorAll("[data-module][data-page][data-json]")];
+let frame;
+
+const native = new BilibiliHost(id => frame.perform(id));
+const navigation = new Navigation(container, home, (module, signal) => {
+    const button = buttons.find(button => button.dataset.module === module);
+    if (!button) return;
+    const host = template.content.firstElementChild.cloneNode(true);
+    const message = host.querySelector("[data-module-message]");
+    frame = new ModuleFrame(button.dataset.page, {
+        signal,
+        headers: {
+            "X-PreferencePanes-JSON": button.dataset.json,
+            ...(button.dataset.css ? { "X-PreferencePanes-CSS": button.dataset.css } : {}),
+        },
+    });
+    frame.addEventListener("confirm", event => {
+        event.preventDefault();
+        native.confirm(event.detail.message).then(event.detail.resolve, event.detail.reject);
+    });
+    frame.addEventListener("notice", event => {
+        event.preventDefault();
+        native.notice(event.detail.message);
+    });
+    frame.addEventListener("change", updateNavigation);
+    frame.element.onload = () => {
+        message.hidden = true;
+    };
+    host.append(frame.element);
+    frame.load().catch(error => {
+        if (!signal.aborted) message.textContent = error.message;
+    });
+    return host;
+});
+
+const statuses = buttons.map(button => {
+    const status = new ModuleStatus(button.querySelector("[data-module-status]"));
+    status.addEventListener("change", () => {
+        button.disabled = status.state.status !== "installed";
+    });
+    button.addEventListener("click", () => navigation.open(button.dataset.module));
+    return { button, status };
+});
+
+/**
+ * 同步当前页面的官方导航状态。
+ * Synchronize the official navigation state for the current page.
+ * @returns {void} 无返回值 / No return value.
+ */
+function updateNavigation() {
+    const state = navigation.current ? frame.state : { title: document.title, actions: [], busy: false };
+    native.update(state);
+}
+
+/**
+ * 每次返回主页并发探测全部配置 Mock。
+ * Probe all configuration Mocks concurrently whenever the home page is entered.
+ * @returns {void} 无返回值 / No return value.
+ */
+function probe() {
+    updateNavigation();
+    if (navigation.current) return;
+    for (const { button, status } of statuses) status.check(button.dataset.json);
+}
+
+navigation.addEventListener("change", probe);
+window.addEventListener("pagehide", event => {
+    if (!event.persisted) {
+        for (const { status } of statuses) status.destroy();
+        navigation.destroy();
+        native.destroy();
+    }
+});
+probe();

package/dist/module/index.html

@@ -9,6 +9,6 @@
     </head>
     <body>
         <main id="preferences"></main>
-        <script type="module" src="/settings/assets/app.mjs?v=0.9.4"></script>
+        <script type="module" src="/settings/assets/app.mjs?v=0.9.6"></script>
     </body>
 </html>

package/dist/preference-panes.mjs

@@ -1,6 +1,6 @@
 var styleURLs = ["https://s1.hdslb.com/bfs/seed/jinkela/short/b-style/theme.min.css","https://s1.hdslb.com/bfs/seed/jinkela/short/b-style/b-style.min.css"];
 
-var defaults = "/* 官方 b-style 负责行布局与配色；本文件只定义面板容器和控件约束。\n * Official b-style owns row layout and colors; this file defines panel containers and control constraints. */\n.pp-panel {\n    --pp-text: var(--text1);\n    --pp-background: var(--bg2);\n    --pp-surface: var(--bg1);\n    --pp-border: var(--line_regular);\n    --pp-muted: var(--text3);\n    --pp-accent: var(--brand_pink);\n    font:\n        15px / 1.5 -apple-system,\n        BlinkMacSystemFont,\n        \"Segoe UI\",\n        sans-serif;\n    color: var(--pp-text);\n    background: var(--pp-background);\n    position: relative;\n    min-height: 100vh;\n}\n.pp-panel * {\n    box-sizing: border-box;\n    letter-spacing: 0;\n}\n.pp-header {\n    height: calc(52px + env(safe-area-inset-top));\n    padding: env(safe-area-inset-top) 12px 0;\n    display: flex;\n    align-items: center;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n    position: sticky;\n    top: 0;\n    z-index: 1;\n}\n.pp-title {\n    flex: 1;\n    text-align: center;\n    font-size: 17px;\n    font-weight: 500;\n    margin: 0;\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n/* 模块图标在正文内；嵌入宿主可使用纯文字原生标题栏。\n * Keep module icons in content so embedded hosts can use text-only native titles. */\n.pp-module-logo {\n    display: none;\n    width: 64px;\n    height: 64px;\n    margin: 8px auto 20px;\n}\n.pp-module-logo:not(:empty) {\n    display: block;\n}\n.pp-module-logo img {\n    display: block;\n    width: 100%;\n    height: 100%;\n    object-fit: contain;\n}\n.pp-nav-spacer {\n    width: 44px;\n    flex: none;\n}\n.pp-panel button {\n    font: inherit;\n    cursor: pointer;\n    border: 0;\n    background: none;\n    color: inherit;\n}\n.pp-panel .pp-back {\n    width: 44px;\n    height: 44px;\n    flex: none;\n    font-size: 34px;\n    line-height: 32px;\n    padding: 0;\n}\n.pp-panel button:disabled {\n    opacity: 0.5;\n    cursor: wait;\n}\n.pp-viewport {\n    position: relative;\n    height: calc(100vh - 52px - env(safe-area-inset-top));\n    overflow: hidden;\n}\n:root[data-preference-panes-embedded] .pp-header {\n    display: none;\n}\n:root[data-preference-panes-embedded] .pp-viewport {\n    height: 100vh;\n}\n@supports (height: 100dvh) {\n    .pp-viewport {\n        height: calc(100dvh - 52px - env(safe-area-inset-top));\n    }\n    :root[data-preference-panes-embedded] .pp-viewport {\n        height: 100dvh;\n    }\n}\n.pp-fields,\n.pp-choice-page,\n.pp-cache-page {\n    position: absolute;\n    inset: 0;\n    overflow: auto;\n    padding: 12px max(16px, calc((100% - 688px) / 2)) calc(28px + env(safe-area-inset-bottom) + var(--pp-keyboard-height, 0px));\n    scroll-padding-bottom: var(--pp-keyboard-height, 0px);\n    background: var(--pp-background);\n}\n.pp-choice-link {\n    display: flex;\n    align-items: center;\n    justify-content: flex-end;\n    gap: 8px;\n    max-width: 45%;\n    min-width: 44px;\n    min-height: 44px;\n    padding: 0;\n    text-align: right;\n    flex: 1;\n}\n.pp-summary {\n    color: var(--pp-muted);\n    font-size: 13px;\n    line-height: 18px;\n    display: -webkit-box;\n    -webkit-line-clamp: 2;\n    -webkit-box-orient: vertical;\n    overflow: hidden;\n    overflow-wrap: anywhere;\n}\n.pp-chevron {\n    color: var(--pp-muted);\n    font-size: 22px;\n    flex: none;\n}\n.pp-editor {\n    flex: none;\n    width: 45%;\n    min-width: 0;\n    min-height: 36px;\n    font: inherit;\n    border: 0;\n}\n.pp-search {\n    width: 100%;\n    margin-bottom: 12px;\n}\n.pp-panel .pp-multiline {\n    display: block;\n}\n.pp-multiline .pp-editor {\n    width: 100%;\n    margin-top: 10px;\n}\n.pp-panel [hidden] {\n    display: none !important;\n}\n.pp-label {\n    flex: 1;\n    min-width: 0;\n}\n.pp-row {\n    min-height: 48px;\n}\n.pp-rows > :last-child {\n    border-bottom: 0 !important;\n}\n.pp-switch {\n    flex: none;\n    accent-color: var(--pp-accent);\n}\n.pp-choice {\n    justify-content: space-between;\n    cursor: pointer;\n}\n.pp-choice input {\n    width: 20px;\n    height: 20px;\n    flex: none;\n    accent-color: var(--pp-accent);\n    margin: 0;\n}\n.pp-description {\n    font-size: 12px;\n    line-height: 1.6;\n    color: var(--pp-muted);\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-module-info {\n    display: flex;\n    gap: 12px;\n    margin: 12px 0;\n}\n.pp-module-details {\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-module-source {\n    color: inherit;\n    text-decoration: underline;\n}\n.pp-error button {\n    min-height: 44px;\n    padding: 8px 12px;\n    border-radius: 6px;\n    background: var(--pp-surface);\n}\n.pp-cache {\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-toast {\n    pointer-events: none;\n    position: fixed;\n    bottom: calc(30px + env(safe-area-inset-bottom));\n    left: 50%;\n    transform: translateX(-50%);\n    max-width: 90vw;\n    padding: 10px 16px;\n    border-radius: 8px;\n    background: #333e;\n    color: white;\n    font-size: 13px;\n    z-index: 20;\n}\n.pp-toast[data-kind=\"error\"] {\n    background: #8d2424;\n}\n.pp-panel :focus-visible {\n    outline: 2px solid var(--pp-accent);\n    outline-offset: -2px;\n}\n";
+var defaults = "/* 官方 b-style 负责行布局与配色；本文件只定义面板容器和控件约束。\n * Official b-style owns row layout and colors; this file defines panel containers and control constraints. */\n.pp-panel {\n    --pp-text: var(--text1);\n    --pp-background: var(--bg2);\n    --pp-surface: var(--bg1);\n    --pp-border: var(--line_regular);\n    --pp-muted: var(--text3);\n    --pp-accent: var(--brand_pink);\n    font:\n        15px / 1.5 -apple-system,\n        BlinkMacSystemFont,\n        \"Segoe UI\",\n        sans-serif;\n    color: var(--pp-text);\n    background: var(--pp-background);\n    position: relative;\n    display: flex;\n    flex-direction: column;\n    height: 100vh;\n}\n.pp-panel * {\n    box-sizing: border-box;\n    letter-spacing: 0;\n}\n.pp-header {\n    flex: none;\n    height: calc(52px + env(safe-area-inset-top));\n    padding: env(safe-area-inset-top) 12px 0;\n    display: flex;\n    align-items: center;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n    position: relative;\n    z-index: 2;\n}\n.pp-title {\n    flex: 1;\n    text-align: center;\n    font-size: 17px;\n    font-weight: 500;\n    margin: 0;\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n/* 模块图标在正文内；嵌入宿主可使用纯文字原生标题栏。\n * Keep module icons in content so embedded hosts can use text-only native titles. */\n.pp-module-logo {\n    display: none;\n    width: 64px;\n    height: 64px;\n    margin: 8px auto 20px;\n}\n.pp-module-logo:not(:empty) {\n    display: block;\n}\n.pp-module-logo img {\n    display: block;\n    width: 100%;\n    height: 100%;\n    object-fit: contain;\n}\n.pp-nav-spacer {\n    width: 44px;\n    flex: none;\n}\n.pp-panel button {\n    font: inherit;\n    cursor: pointer;\n    border: 0;\n    background: none;\n    color: inherit;\n}\n.pp-panel .pp-back {\n    width: 44px;\n    height: 44px;\n    flex: none;\n    font-size: 34px;\n    line-height: 32px;\n    padding: 0;\n}\n.pp-panel button:disabled {\n    opacity: 0.5;\n    cursor: wait;\n}\n/* 固定工具区与滚动视口共用弹性布局，不按工具栏高度拼接页面偏移。\n * Fixed tools and the scrolling viewport share a flex layout without toolbar-height offsets. */\n.pp-toolbar {\n    flex: none;\n    padding: 12px max(16px, calc((100% - 688px) / 2));\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n}\n.pp-viewport {\n    position: relative;\n    flex: 1;\n    min-height: 0;\n    overflow: hidden;\n}\n:root[data-preference-panes-embedded] .pp-header {\n    display: none;\n}\n@supports (height: 100dvh) {\n    .pp-panel {\n        height: 100dvh;\n    }\n}\n.pp-fields,\n.pp-choice-page,\n.pp-cache-page {\n    position: absolute;\n    inset: 0;\n    overflow: auto;\n    padding: 12px max(16px, calc((100% - 688px) / 2)) calc(28px + env(safe-area-inset-bottom) + var(--pp-keyboard-height, 0px));\n    scroll-padding-bottom: var(--pp-keyboard-height, 0px);\n    background: var(--pp-background);\n}\n.pp-choice-link {\n    display: flex;\n    align-items: center;\n    justify-content: flex-end;\n    gap: 8px;\n    max-width: 45%;\n    min-width: 44px;\n    min-height: 44px;\n    padding: 0;\n    text-align: right;\n    flex: 1;\n}\n.pp-summary {\n    color: var(--pp-muted);\n    font-size: 13px;\n    line-height: 18px;\n    display: -webkit-box;\n    -webkit-line-clamp: 2;\n    -webkit-box-orient: vertical;\n    overflow: hidden;\n    overflow-wrap: anywhere;\n}\n.pp-chevron {\n    color: var(--pp-muted);\n    font-size: 22px;\n    flex: none;\n}\n.pp-editor {\n    flex: none;\n    width: 45%;\n    min-width: 0;\n    min-height: 36px;\n    font: inherit;\n    border: 0;\n}\n.pp-search {\n    width: 100%;\n    margin: 0;\n}\n.pp-panel .pp-multiline {\n    display: block;\n}\n.pp-multiline .pp-editor {\n    width: 100%;\n    margin-top: 10px;\n}\n.pp-panel [hidden] {\n    display: none !important;\n}\n.pp-label {\n    flex: 1;\n    min-width: 0;\n}\n.pp-row {\n    min-height: 48px;\n}\n.pp-rows > :last-child {\n    border-bottom: 0 !important;\n}\n.pp-switch {\n    flex: none;\n    accent-color: var(--pp-accent);\n}\n.pp-choice {\n    justify-content: space-between;\n    cursor: pointer;\n}\n.pp-choice input {\n    width: 20px;\n    height: 20px;\n    flex: none;\n    accent-color: var(--pp-accent);\n    margin: 0;\n}\n.pp-description {\n    font-size: 12px;\n    line-height: 1.6;\n    color: var(--pp-muted);\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-module-info {\n    display: flex;\n    gap: 12px;\n    margin: 12px 0;\n}\n.pp-module-details {\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-module-source {\n    color: inherit;\n    text-decoration: underline;\n}\n.pp-error button {\n    min-height: 44px;\n    padding: 8px 12px;\n    border-radius: 6px;\n    background: var(--pp-surface);\n}\n.pp-cache {\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-toast {\n    pointer-events: none;\n    position: fixed;\n    bottom: calc(30px + env(safe-area-inset-bottom));\n    left: 50%;\n    transform: translateX(-50%);\n    max-width: 90vw;\n    padding: 10px 16px;\n    border-radius: 8px;\n    background: #333e;\n    color: white;\n    font-size: 13px;\n    z-index: 20;\n}\n.pp-toast[data-kind=\"error\"] {\n    background: #8d2424;\n}\n.pp-panel :focus-visible {\n    outline: 2px solid var(--pp-accent);\n    outline-offset: -2px;\n}\n";
 
 /**
  * 校验原始路径片段，不进行 URL 编码转换。
@@ -826,10 +826,13 @@ function mountPanel(root, catalog) {
     logo.setAttribute("aria-hidden", "true");
     const image = icon(catalog.module.metadata, "");
     if (image) logo.append(image);
+    const toolbar = element("div", "pp-toolbar");
+    toolbar.setAttribute("role", "search");
+    toolbar.hidden = true;
     const viewport = element("div", "pp-viewport");
     let toast;
     header.append(back, heading, trailing);
-    shell.append(header, viewport);
+    shell.append(header, toolbar, viewport);
     root.append(shell);
     // 嵌入模式向宿主发布导航状态，宿主不读取或修改模块内部 DOM。
     // Embedded mode publishes navigation state without host reads or mutations of the module DOM.
@@ -920,6 +923,7 @@ function mountPanel(root, catalog) {
     async function open(module) {
         const version = ++generation;
         active = module;
+        toolbar.hidden = true;
         back.disabled = window.history.length <= 1;
         heading.textContent = module;
         publishNavigation();
@@ -949,7 +953,7 @@ function mountPanel(root, catalog) {
         search.setAttribute("aria-label", "搜索设置");
         const searchField = fieldControl(search);
         searchField.classList.add("pp-search");
-        view.append(searchField);
+        toolbar.replaceChildren(searchField);
         const searchRows = [];
         /**
          * 挂载后执行的多行高度更新
@@ -969,6 +973,7 @@ function mountPanel(root, catalog) {
          */
         const updateNavigation = () => {
             const editor = editors.get(navigation.current);
+            toolbar.hidden = Boolean(navigation.current);
             heading.textContent = editor?.title ?? definition.metadata?.name ?? active;
             back.disabled = saving || !navigation.canGoBack;
             publishNavigation();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nsnanocat/preference-panes",
-    "version": "0.9.4",
+    "version": "0.9.6",
     "description": "Shared settings API runtime for JavaScript proxy modules",
     "author": "VirgilClyne <Virgil@nanocat.me>",
     "homepage": "https://NSNanoCat.github.io/preference-panes",