@lynn123411/dsh-maple-theme 0.0.0-stage → 0.1.0

package/src/client/card.tsx

@@ -0,0 +1,179 @@
+/**
+ * 宿主「插件」页上的配置卡片：Maple 主题的全部旋钮。
+ *
+ * 改动即时生效：控件的每一次变化都直接写进配置表单，表单回写快照，投影订阅把值
+ * 写到 <html> 上，样式表不重建。没有「保存」按钮——这几个旋钮都是所见即所得的，
+ * 加一步保存只会让人以为没生效。
+ */
+import { useEffect, useState } from 'react';
+import * as React from 'react';
+import { Input, SegmentedControl, Switch } from '@deepseek-ai/dsh-client-ui-primitives';
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import { readSettings, type MapleForm } from './binding.ts';
+import { DEFAULT_SETTINGS, type MapleSettings } from './settings.ts';
+import { NS } from './locales.ts';
+
+/** 标题配色的三个选项：值、文案键、面板 id 后缀。 */
+const HEADING_OPTIONS = [
+  { value: 'colorful', key: 'card.headingColorColorful' },
+  { value: 'accent', key: 'card.headingColorAccent' },
+  { value: 'text', key: 'card.headingColorText' },
+] as const;
+
+/** 一行「标题 + 说明 + 控件」。 */
+function Row({ title, hint, children }: {
+  title: string;
+  hint?: string | undefined;
+  children: React.ReactNode;
+}): React.ReactElement {
+  return (
+    <div className="dsh-maple-row">
+      <div className="dsh-maple-row-info">
+        <div className="dsh-maple-row-title">{title}</div>
+        {hint !== undefined && <div className="dsh-maple-row-hint">{hint}</div>}
+      </div>
+      <div className="dsh-maple-row-field">{children}</div>
+    </div>
+  );
+}
+
+/**
+ * 一个数字旋钮：本地保存输入中的字符串，失焦或回车时才提交。
+ *
+ * 不逐键提交：输入 `1.75` 的中途会经过 `1`、`1.` 这些值，逐键写会让页面在中间态闪一下。
+ * @param props.value - 当前生效的值。
+ * @param props.onCommit - 提交一个合法值。
+ */
+function NumberField({ value, min, max, step, unit, label, onCommit }: {
+  value: number;
+  min: number;
+  max: number;
+  step: number;
+  unit: string;
+  label: string;
+  onCommit: (next: number) => void;
+}): React.ReactElement {
+  const [text, setText] = useState(String(value));
+  // 外部改了值（别处写入、恢复默认）就跟着换，但正在编辑时不打断。
+  useEffect(() => { setText(String(value)) }, [value]);
+  const commit = (): void => {
+    const parsed = Number(text);
+    if (!Number.isFinite(parsed)) { setText(String(value)); return; }
+    const clamped = Math.min(max, Math.max(min, Math.round(parsed / step) * step));
+    setText(String(clamped));
+    if (clamped !== value) onCommit(clamped);
+  };
+  return (
+    <>
+      <Input
+        className="dsh-maple-number"
+        type="number"
+        inputMode="decimal"
+        min={min}
+        max={max}
+        step={step}
+        value={text}
+        aria-label={label}
+        onChange={(event: React.ChangeEvent<HTMLInputElement>) => { setText(event.target.value) }}
+        onBlur={commit}
+        onKeyDown={(event: React.KeyboardEvent<HTMLInputElement>) => {
+          if (event.key === 'Enter') { event.currentTarget.blur(); }
+        }}
+      />
+      <span className="dsh-maple-unit">{unit}</span>
+    </>
+  );
+}
+
+/**
+ * 渲染配置卡片。
+ * @param props - 座位给的 `t`，加上本插件在 `inject` 里投出去的那张表单。
+ * @returns 卡片的元素树。
+ */
+export function MapleThemeCard(
+  props: PropsRuntime<'plugins.bundle.config'> & PropsLocale<typeof NS> & { form: MapleForm },
+): React.ReactElement {
+  // 座位在 `locale: NS` 时把绑定好的 t 挂在 `t` 上；类型声明里它是运行期注入的，这里取出来。
+  const { form } = props;
+  const t = (key: keyof typeof import('./locales.ts').en): string =>
+    (props as unknown as { t: (k: string) => string }).t(key);
+  const [settings, setSettings] = useState<MapleSettings | undefined>(() => readSettings(form));
+  const [available, setAvailable] = useState(() => form.getSnapshot().status !== 'unavailable');
+
+  useEffect(() => {
+    const sync = (): void => {
+      setSettings(readSettings(form));
+      setAvailable(form.getSnapshot().status !== 'unavailable');
+    };
+    sync();
+    return form.subscribe(sync);
+  }, [form]);
+
+  if (!available) return <div className="dsh-maple-card"><div className="dsh-maple-empty">{t('card.unavailable')}</div></div>;
+
+  const current = settings ?? DEFAULT_SETTINGS;
+  const write = (field: keyof MapleSettings, value: unknown): void => { void form.set(field, value); };
+
+  return (
+    <div className="dsh-maple-card">
+      <section className="dsh-maple-group">
+        <div className="dsh-maple-group-title">{t('card.colors')}</div>
+        <Row title={t('card.hueLight')} hint={t('card.hueLightHint')}>
+          <NumberField value={current.hueLight} min={0} max={360} step={1} unit="°"
+            label={t('card.hueLight')} onCommit={(next) => { write('hueLight', next) }} />
+        </Row>
+        <Row title={t('card.hueDark')} hint={t('card.hueDarkHint')}>
+          <NumberField value={current.hueDark} min={0} max={360} step={1} unit="°"
+            label={t('card.hueDark')} onCommit={(next) => { write('hueDark', next) }} />
+        </Row>
+      </section>
+
+      <section className="dsh-maple-group">
+        <div className="dsh-maple-group-title">{t('card.typography')}</div>
+        <Row title={t('card.lineHeight')} hint={t('card.lineHeightHint')}>
+          <NumberField value={current.lineHeight} min={1.4} max={2} step={0.05} unit="×"
+            label={t('card.lineHeight')} onCommit={(next) => { write('lineHeight', next) }} />
+        </Row>
+        <Row title={t('card.paragraphGap')} hint={t('card.paragraphGapHint')}>
+          <NumberField value={current.paragraphGap} min={4} max={24} step={1} unit="px"
+            label={t('card.paragraphGap')} onCommit={(next) => { write('paragraphGap', next) }} />
+        </Row>
+      </section>
+
+      <section className="dsh-maple-group">
+        <div className="dsh-maple-group-title">{t('card.headings')}</div>
+        <Row title={t('card.headingColor')}>
+          <SegmentedControl
+            id="dsh-maple-heading"
+            value={current.headingColor}
+            label={t('card.headingColor')}
+            options={HEADING_OPTIONS.map(option => ({ value: option.value, label: t(option.key) }))}
+            onChange={(next) => { write('headingColor', next) }}
+          />
+        </Row>
+        <Row title={t('card.headingIndicator')} hint={t('card.headingIndicatorHint')}>
+          <Switch checked={current.headingIndicator} label={t('card.headingIndicator')}
+            onChange={(next) => { write('headingIndicator', next) }} />
+        </Row>
+      </section>
+
+      <section className="dsh-maple-group">
+        <div className="dsh-maple-group-title">{t('card.code')}</div>
+        <Row title={t('card.codePalette')} hint={t('card.codePaletteHint')}>
+          <Switch checked={current.codePalette} label={t('card.codePalette')}
+            onChange={(next) => { write('codePalette', next) }} />
+        </Row>
+      </section>
+
+      <section className="dsh-maple-group">
+        <div className="dsh-maple-group-title">{t('card.shell')}</div>
+        <Row title={t('card.shellSkin')} hint={t('card.shellSkinHint')}>
+          <Switch checked={current.shellSkin} label={t('card.shellSkin')}
+            onChange={(next) => { write('shellSkin', next) }} />
+        </Row>
+      </section>
+
+      <div className="dsh-maple-note">{t('card.scope')}</div>
+    </div>
+  );
+}

package/src/client/css.d.ts

@@ -0,0 +1,5 @@
+/** `?inline` 导入的样式表是构建期内联进来的字符串，不是要交给打包器处理的 CSS 模块。 */
+declare module '*.css?inline' {
+  const css: string;
+  export default css;
+}

package/src/client/index.ts

@@ -0,0 +1,149 @@
+/**
+ * Maple 主题的浏览器半边：注入样式表、把配置投影到 `<html>`、在宿主「插件」页上挂配置卡片。
+ *
+ * 三件事各有归属：
+ *   1. 样式表在 `apply()` 里注入，标签带 `data-plugin` / `data-plugin-css`：client-modules
+ *      按前者在卸载与热更时删掉它们（docs/rules/plugin-ui.md「覆盖宿主控件的样式」）。
+ *   2. 投影订阅本插件那一行的配置表单，值变了只改 `<html>` 上的属性与变量，样式表不重建。
+ *   3. 卡片走 `plugins.bundle.config`，key 是 bundle 的 npm 包名；宿主「插件」页没挂载时
+ *      这个座位不存在，所以注册必须包在 `slots.inject` 里，并与 `configForms.whileServed`
+ *      串起来——宿主没服务这份配置，就一个字的界面都不出现。
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+// 类型只读：这几个包的浏览器半边把座位契约、`ctx.configForms` 与 `ctx.locale` 合并进 Context。
+import type {} from '@deepseek-ai/dsh-client-locale/client';
+import type {} from '@deepseek-ai/dsh-client-ui-plugin-manager/client';
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client';
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client';
+import { bindProjection, BUNDLE_NAME, BUNDLE_CONFIG_SLOT, SETTINGS_NAMESPACE, type MapleForm } from './binding.ts';
+import { CARD_CSS } from './card-css.ts';
+import { MapleThemeCard } from './card.tsx';
+import { NS, en, zh } from './locales.ts';
+import tokens from './styles/tokens.css?inline';
+import { MAPLE_TOKENS, THEME_SOURCE } from './tokens.ts';
+import markdown from './styles/markdown.css?inline';
+import shell from './styles/shell.css?inline';
+
+export { NS } from './locales.ts';
+export {
+  BUNDLE_CONFIG_SLOT, BUNDLE_NAME, SETTINGS_NAMESPACE, bindProjection, readSettings,
+} from './binding.ts';
+export { MapleThemeCard } from './card.tsx';
+export {
+  DEFAULT_SETTINGS, HEADING_ATTRIBUTE, INDICATOR_ATTRIBUTE, CODE_ATTRIBUTE, ROOT_ATTRIBUTE, ROOT_VARIABLES,
+  applyProjection, clearProjection, clampNumber, normalizeSettings, projectSettings,
+} from './settings.ts';
+
+/** 包名：样式表标签的归属键，也是浏览器 bundle 的自注册 id。 */
+export const name = '@lynn123411/dsh-maple-theme';
+
+/**
+ * 声明的服务：`configForms` 读本插件那一行的配置，`slots` 与 `locale` 画配置卡片，
+ * `theme` 把两套调色板交给宿主的主题通道。
+ * 漏声明不会报错，只会让整个浏览器半边在页面里消失（docs/rules/client-wiring.md）。
+ */
+export const inject = ['configForms', 'slots', 'locale', 'theme'];
+
+/** 本插件的样式表：归属键按「包名/文件名」拼，卸载时整批删。 */
+const SHEETS: readonly (readonly [string, string])[] = [
+  ['tokens.css', tokens],
+  ['markdown.css', markdown],
+  ['shell.css', shell],
+  ['card.css', CARD_CSS],
+];
+
+/**
+ * 注入本插件的样式表；同一个键已存在时替换内容而不是再插一张。
+ * 键按文件走：热更后重新执行这个模块时，新内容覆盖旧标签，不会叠出第二份。
+ */
+function injectStyles(): void {
+  if (typeof document === 'undefined') return;
+  for (const [file, css] of SHEETS) {
+    const key = `${name}/${file}`;
+    const existing = document.head.querySelector<HTMLStyleElement>(`style[data-plugin-css="${key}"]`);
+    const tag = existing ?? document.createElement('style');
+    tag.dataset.plugin = name;
+    tag.dataset.pluginCss = key;
+    tag.textContent = css;
+    if (existing === null) document.head.appendChild(tag);
+  }
+}
+
+/** 撤掉本插件的样式标签。 */
+function removeStyles(): void {
+  if (typeof document === 'undefined') return;
+  for (const tag of document.head.querySelectorAll(`style[data-plugin="${name}"]`)) tag.remove();
+}
+
+/** 浏览器上下文里本插件用到的成员。 */
+interface ClientServices {
+  configForms: {
+    get(namespace: string): MapleForm;
+    whileServed(namespaces: readonly string[], register: (served: ReadonlySet<string>) => () => void): () => void;
+  };
+  slots: {
+    inject(slot: string, register: () => () => void): () => void;
+    register(options: Record<string, unknown>, component: unknown): () => void;
+  };
+  locale: {
+    register(namespace: string, dictionaries: { zh: unknown; en: unknown }): () => void;
+  };
+  theme: {
+    overrideTokens(source: string, tokens: Record<string, { light: string; dark: string }>): () => void;
+  };
+}
+
+/**
+ * 插件本体。
+ * @param ctx - 客户端根上下文。
+ */
+export function apply(ctx: ClientContext): void {
+  const services = ctx as unknown as ClientServices;
+
+  ctx.effect(() => {
+    injectStyles();
+    return () => { removeStyles(); };
+  }, 'dsh-maple-theme: stylesheets');
+
+  // 配色：走宿主的主题通道，由它写到 body 的行内样式上（docs/web-styling.md 的所有权归主题，
+  // 功能包消费令牌而不是另立一份全局主题）。disposer 会把这层覆盖整份撤掉。
+  ctx.effect(
+    () => services.theme.overrideTokens(THEME_SOURCE, MAPLE_TOKENS),
+    'dsh-maple-theme: palette',
+  );
+
+  ctx.effect(
+    () => services.locale.register(NS, { zh, en }),
+    'dsh-maple-theme: dictionaries',
+  );
+
+  // 投影：配置一变就重写 <html>，卸载时把痕迹撤干净。
+  ctx.effect(() => {
+    if (typeof document === 'undefined') return () => {};
+    return bindProjection(document.documentElement, services.configForms.get(SETTINGS_NAMESPACE));
+  }, 'dsh-maple-theme: projection');
+
+  // 配置卡片：宿主「插件」页挂载时才注册，宿主没服务这份配置就不出现。
+  ctx.effect(
+    () => services.configForms.whileServed([SETTINGS_NAMESPACE], () => services.slots.inject(
+      BUNDLE_CONFIG_SLOT,
+      () => slotsRegister(services, () => ({
+        name: BUNDLE_CONFIG_SLOT,
+        key: BUNDLE_NAME,
+        locale: NS,
+        inject: () => ({ form: services.configForms.get(SETTINGS_NAMESPACE) }),
+      })),
+    )),
+    'dsh-maple-theme: plugins page config',
+  );
+}
+
+/**
+ * 把「注册项的选项」与组件绑在一起，抽出来只为让上面那段读起来是三层而不是五层。
+ * @param services - 上下文里用到的服务。
+ * @param options - 注册项的选项工厂（每次注册都新建一份）。
+ * @returns 注册的 disposer。
+ */
+function slotsRegister(services: ClientServices, options: () => Record<string, unknown>): () => void {
+  return services.slots.register(options(), MapleThemeCard);
+}

package/src/client/locales.ts

@@ -0,0 +1,60 @@
+/** Maple 主题的界面文案。键集与英文逐一对齐，自检会查这一条。 */
+export const NS = 'mapletheme';
+
+/** 英文文案。 */
+export const en = {
+  'card.colors': 'Colors',
+  'card.hueLight': 'Light hue',
+  'card.hueLightHint': 'Base hue the whole light palette is derived from. Maple ships 35 (warm white).',
+  'card.hueDark': 'Dark hue',
+  'card.hueDarkHint': 'Base hue the whole dark palette is derived from. Maple ships 207 (cool grey).',
+  'card.typography': 'Typing',
+  'card.lineHeight': 'Line height',
+  'card.lineHeightHint': 'Line height for conversation body text. Tighter than Maple’s 1.8 because chat lines run narrower.',
+  'card.paragraphGap': 'Paragraph gap',
+  'card.paragraphGapHint': 'Space between two paragraphs in an answer, in pixels. Looser than Maple’s 8.',
+  'card.headings': 'Headings',
+  'card.headingColor': 'Heading color',
+  'card.headingColorColorful': 'Six colors',
+  'card.headingColorAccent': 'Accent',
+  'card.headingColorText': 'Body text',
+  'card.headingIndicator': 'Level marker',
+  'card.headingIndicatorHint': 'Show H1–H6 to the left of a heading while the pointer rests on it.',
+  'card.code': 'Code',
+  'card.codePalette': 'Maple syntax colors',
+  'card.codePaletteHint': 'Recolor fenced code blocks with the Maple syntax palette.',
+  'card.shell': 'Surroundings',
+  'card.shellSkin': 'Sidebar and tabs',
+  'card.shellSkinHint': 'Round the sidebar rows and the active tab, drop the seam under the session header, and give the input card Maple paper.',
+  'card.scope': 'The palette is global; headings, quotes, tables, lists and rules only change inside conversation answers.',
+  'card.unavailable': 'The Host does not serve this configuration right now.',
+} as const;
+
+/** 中文文案。 */
+export const zh: Record<keyof typeof en, string> = {
+  'card.colors': '配色',
+  'card.hueLight': '浅色基础色相',
+  'card.hueLightHint': '浅色整套颜色由这个色相推导。Maple 出厂值是 35（暖白）。',
+  'card.hueDark': '深色基础色相',
+  'card.hueDarkHint': '深色整套颜色由这个色相推导。Maple 出厂值是 207（冷灰）。',
+  'card.typography': '打字体验',
+  'card.lineHeight': '行高',
+  'card.lineHeightHint': '对话正文的行高倍数。比 Maple 的 1.8 紧一档，对话的行宽比笔记窄。',
+  'card.paragraphGap': '段落间距',
+  'card.paragraphGapHint': '一个回答里两段之间空多少像素。比 Maple 的 8 松一档。',
+  'card.headings': '标题',
+  'card.headingColor': '标题颜色',
+  'card.headingColorColorful': '六级换色',
+  'card.headingColorAccent': '强调色',
+  'card.headingColorText': '正文色',
+  'card.headingIndicator': '等级标记',
+  'card.headingIndicatorHint': '指针停在标题上时，在左边显示 H1–H6。',
+  'card.code': '代码',
+  'card.codePalette': 'Maple 语法配色',
+  'card.codePaletteHint': '用 Maple 的调色板给围栏代码块换语法色。',
+  'card.shell': '周边',
+  'card.shellSkin': '侧栏与标签条',
+  'card.shellSkinHint': '侧栏行与活动标签改成圆角，去掉会话头部下面那条接缝，输入卡换成 Maple 的纸色。',
+  'card.scope': '配色是全局的；标题、引用、表格、列表与分隔线只在对话正文里换样子。',
+  'card.unavailable': '宿主当前没有提供这份配置。',
+};

package/src/client/settings.ts

@@ -0,0 +1,171 @@
+/**
+ * 配置到 DOM 的投影：把一份已解析的配置算成 `<html>` 上要写的属性与自定义变量。
+ *
+ * 这里是纯函数，不碰 document、不读配置源——浏览器半边负责把它的结果写到页面上，
+ * 自检直接 import 这个文件断言映射，不用起 DOM。
+ *
+ * 为什么写在 `<html>` 而不是 `body`：宿主把令牌声明在 `body` 上，我们的样式表也要覆盖
+ * 同名变量，写在同一层只能靠注入顺序取胜；写到 `<html>` 上，`body` 里那些 `var(--maple-*)`
+ * 一律读得到，而两套配色各自的选择器 (`body` / `body[data-ds-dark-theme]`) 与宿主同形，
+ * 只靠后注入这一条优势。**但开关必须写在祖先上**：属性选择器要多一个 key 才能稳定压过宿主。
+ */
+
+/** 本插件在 `<html>` 上用的根属性：开着时才加，关掉整层样式一并失效。 */
+export const ROOT_ATTRIBUTE = 'data-maple-theme';
+
+/** 标题配色方式落到 `<html>` 上的属性名。 */
+export const HEADING_ATTRIBUTE = 'data-maple-heading';
+
+/** 标题等级标记的开关属性名。 */
+export const INDICATOR_ATTRIBUTE = 'data-maple-indicator';
+
+/** 代码配色的开关属性名。 */
+export const CODE_ATTRIBUTE = 'data-maple-code';
+
+/** 外壳装饰（侧栏、标签条、输入区）的开关属性名。 */
+export const SHELL_ATTRIBUTE = 'data-maple-shell';
+
+/** 一份配置投影出来的结果：要写的属性与变量。 */
+export interface MapleProjection {
+  /** `<html>` 上要设的属性（值为 `null` 表示删掉）。 */
+  attributes: Record<string, string | null>;
+  /** `<html>` 行内样式上要写的自定义变量（值为 `null` 表示删掉）。 */
+  variables: Record<string, string | null>;
+}
+
+/** 本插件写在 `<html>` 上的全部变量名：撤痕迹时按这张表逐个删，不靠猜。 */
+export const ROOT_VARIABLES = [
+  '--maple-hue-light',
+  '--maple-hue-dark',
+  '--maple-line-height',
+  '--maple-p-gap',
+] as const;
+
+/** 配置里取色相关字段的兜底：宿主没给值时按 Maple 出厂值走。 */
+export interface MapleSettings {
+  hueLight: number;
+  hueDark: number;
+  lineHeight: number;
+  paragraphGap: number;
+  headingColor: 'colorful' | 'accent' | 'text';
+  headingIndicator: boolean;
+  codePalette: boolean;
+  shellSkin: boolean;
+}
+
+/** 出厂值，与宿主半边 Config 的默认值同一组数字。 */
+export const DEFAULT_SETTINGS: Readonly<MapleSettings> = Object.freeze({
+  hueLight: 35,
+  hueDark: 207,
+  lineHeight: 1.75,
+  paragraphGap: 10,
+  headingColor: 'colorful',
+  headingIndicator: true,
+  codePalette: true,
+  shellSkin: true,
+});
+
+/**
+ * 把一个数夹进闭区间；不是有限数就用兜底值。
+ * 手改过的设置文档可能存进越界值或字符串，投影这一步不信任它。
+ * @param value - 候选值。
+ * @param min - 下界。
+ * @param max - 上界。
+ * @param fallback - 不是有限数时用它。
+ * @returns 夹好的数。
+ */
+export function clampNumber(value: unknown, min: number, max: number, fallback: number): number {
+  if (typeof value !== 'number' && typeof value !== 'string') return fallback;
+  // 空串、全空白，以及 null 被 Number 读成 0 的那一类，都不算「给了一个数」。
+  if (typeof value === 'string' && value.trim() === '') return fallback;
+  const parsed = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, parsed));
+}
+
+/**
+ * 把宿主可能给出的任意值收成一份可信的配置。
+ * @param raw - 配置源里的原始值（可能缺字段、可能越界）。
+ * @returns 每个字段都在合法范围内的一份配置。
+ */
+export function normalizeSettings(raw: Partial<MapleSettings> | undefined | null): MapleSettings {
+  const source = raw ?? {};
+  const heading = source.headingColor;
+  return {
+    hueLight: clampNumber(source.hueLight, 0, 360, DEFAULT_SETTINGS.hueLight),
+    hueDark: clampNumber(source.hueDark, 0, 360, DEFAULT_SETTINGS.hueDark),
+    lineHeight: clampNumber(source.lineHeight, 1.4, 2, DEFAULT_SETTINGS.lineHeight),
+    paragraphGap: clampNumber(source.paragraphGap, 4, 24, DEFAULT_SETTINGS.paragraphGap),
+    headingColor: heading === 'colorful' || heading === 'accent' || heading === 'text'
+      ? heading
+      : DEFAULT_SETTINGS.headingColor,
+    headingIndicator: source.headingIndicator ?? DEFAULT_SETTINGS.headingIndicator,
+    codePalette: source.codePalette ?? DEFAULT_SETTINGS.codePalette,
+    shellSkin: source.shellSkin ?? DEFAULT_SETTINGS.shellSkin,
+  };
+}
+
+/**
+ * 算出一份配置该在 `<html>` 上留下什么。
+ *
+ * 关掉的开关写成 `null`（调用方删属性），而不是写 `off`：属性不存在时那批规则整段不匹配，
+ * 少一个匹配分支也少一处能跟宿主撞车的地方。
+ * @param settings - 已收拢到合法范围的配置。
+ * @param enabled - 整个主题是否启用；关掉时只留一个「关」标记，其余全部撤掉。
+ * @returns 要写的属性与变量。
+ */
+export function projectSettings(settings: MapleSettings, enabled = true): MapleProjection {
+  if (!enabled) {
+    const variables: Record<string, null> = {};
+    for (const name of ROOT_VARIABLES) variables[name] = null;
+    return {
+      attributes: {
+        [ROOT_ATTRIBUTE]: null,
+        [HEADING_ATTRIBUTE]: null,
+        [INDICATOR_ATTRIBUTE]: null,
+        [CODE_ATTRIBUTE]: null,
+        [SHELL_ATTRIBUTE]: null,
+      },
+      variables,
+    };
+  }
+  return {
+    attributes: {
+      [ROOT_ATTRIBUTE]: 'on',
+      [HEADING_ATTRIBUTE]: settings.headingColor,
+      [INDICATOR_ATTRIBUTE]: settings.headingIndicator ? 'on' : null,
+      [CODE_ATTRIBUTE]: settings.codePalette ? 'on' : null,
+      [SHELL_ATTRIBUTE]: settings.shellSkin ? 'on' : null,
+    },
+    variables: {
+      '--maple-hue-light': String(settings.hueLight),
+      '--maple-hue-dark': String(settings.hueDark),
+      '--maple-line-height': String(settings.lineHeight),
+      '--maple-p-gap': `${settings.paragraphGap}px`,
+    },
+  };
+}
+
+/**
+ * 把投影写到页面上；同一个元素重复调用是幂等的。
+ * @param root - 文档根元素（真实浏览器里是 `document.documentElement`）。
+ * @param projection - {@link projectSettings} 的结果。
+ */
+export function applyProjection(root: HTMLElement, projection: MapleProjection): void {
+  for (const [attribute, value] of Object.entries(projection.attributes)) {
+    if (value === null) root.removeAttribute(attribute);
+    else root.setAttribute(attribute, value);
+  }
+  for (const [property, value] of Object.entries(projection.variables)) {
+    if (value === null) root.style.removeProperty(property);
+    else root.style.setProperty(property, value);
+  }
+}
+
+/**
+ * 撤掉本插件在页面上留下的一切痕迹（卸载与关掉主题都走这一条）。
+ * @param root - 文档根元素。
+ */
+export function clearProjection(root: HTMLElement): void {
+  applyProjection(root, projectSettings(normalizeSettings(undefined), false));
+}