@kidli1412/dsh-token-heatmap 0.1.6 → 0.4.2

package/lib/client.js

@@ -2,21 +2,23 @@
  * dsh-token-heatmap — browser half.
  *
  * Hand-written `__ModuleLoader__` bundle (no build step): registers into the
- * conversation `input.dock` list slot and renders a GitHub-style heatmap of a
- * SELECTABLE CALENDAR YEAR (Jan 1 – Dec 31; columns = weeks, rows = Mon..Sun,
- * all seven weekday labels on the left) plus today / this-month / all-time
- * totals and a ‹year› year selector next to the stats. It also registers a
- * settings card into the official `settings.plugin.item` seat
- * (设置 → 插件 → 插件配置) with a display switch and a green/blue palette
- * choice, persisted through the `token-heatmap` settings namespace (settings
- * scope).
+ * conversation `input.dock` list slot and renders a GitHub-style token-usage
+ * card on the new-session (hero) screen — a calendar-year grid (Jan 1 – Dec 31;
+ * columns = weeks, rows = Mon..Sun, all seven weekday labels on the left) or a
+ * single-month calendar, switchable from the header, plus today / this-month /
+ * all-time totals and a ‹period› stepper. The card configures ITSELF through a
+ * ⚙ panel (palette + default view) persisted in the `token-heatmap` settings
+ * namespace (settings scope); it deliberately does not register into the
+ * official `settings.plugin.item` seat (设置 → 插件 → 插件配置), so all of its
+ * settings live on the card.
  *
- * The card is shown ONLY on the new-session (hero) screen — gated on
- * `session.composerPhase === "blank"` — and is positioned visually BELOW the
- * composer input card via a flex `order` on the dock wrapper (the dock's DOM
- * site sits above the bar, but the composer stack is a flex column and the
- * framework's true below-card seat `composer.dock` is disabled on the hero
- * screen).
+ * The card is shown ONLY on the new-session (hero) screen — gated on the
+ * boolean `session.blank`, with `composerPhase === "blank"` as the pre-0.1.2
+ * fallback — and is positioned visually BELOW the composer input card via a
+ * flex `order` on the dock wrapper (the dock's DOM site sits above the bar, but
+ * the composer stack is a flex column and the framework's true below-card seat
+ * `composer.dock` is disabled on the hero screen). There is no display switch:
+ * the hero screen always renders it.
  *
  * Cell colors use ABSOLUTE token thresholds (not window-relative ranks), so
  * a huge day is always dark regardless of its neighbours:
@@ -35,21 +37,34 @@ window.__ModuleLoader__.load({
 
 		let react = require("react");
 		let react_jsx_runtime = require("react/jsx-runtime");
+		// Only for the settings panel, which is PORTALED to document.body so the
+		// card's own box can never clip it (the pattern the stat pills use).
+		let reactDom = require("react-dom");
 
 		//#region css
 		const css = [
-			".thm_dock{box-sizing:border-box;width:100%;max-width:var(--dsh-composer-card-max-width,780px);margin:0 auto;padding:0 16px 2px}",
-			".thm_card{box-sizing:border-box;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-base);border-radius:12px;padding:10px 12px 12px;display:flex;flex-direction:column;gap:8px}",
+			// Surface matched to the composer card above it (measured computed
+			// styles): same 22px radius, no hard border — the edge is the same
+			// hairline + soft drop the composer uses — and the same 16px inner
+			// inset, so the card's text lines up with the composer's placeholder.
+			".thm_dock{box-sizing:border-box;width:100%;max-width:var(--dsh-composer-card-max-width,780px);margin:0 auto;padding:0;display:flex;flex-direction:column;gap:8px}",
+			".thm_card{box-sizing:border-box;background:var(--dsw-alias-bg-base);border:none;border-radius:22px;box-shadow:0 0 0 .5px rgba(0,0,0,.1),0 4px 16px rgba(0,0,0,.03),0 0 24px rgba(0,0,0,.03);padding:14px 16px 16px;display:flex;flex-direction:column;gap:8px}",
 			".thm_head{flex-wrap:wrap;align-items:baseline;gap:4px 12px;display:flex}",
 			".thm_title{color:var(--dsw-alias-label-primary);font-size:12px;font-weight:600;line-height:18px}",
 			".thm_stat{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px}",
 			".thm_statLabel{margin-right:4px}",
 			".thm_statValue{color:var(--dsw-alias-label-primary);font-size:12px;font-weight:600;line-height:18px;font-variant-numeric:tabular-nums}",
-			".thm_yearNav{align-items:center;gap:2px;display:inline-flex}",
+			".thm_nav{align-items:center;gap:2px;display:inline-flex}",
 			".thm_yearBtn{cursor:pointer;color:var(--dsw-alias-label-tertiary);background:0 0;border:none;border-radius:4px;padding:0 5px;font-size:13px;line-height:18px}",
 			".thm_yearBtn:hover:not(:disabled){color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-interactive-bg-hover)}",
 			".thm_yearBtn:disabled{opacity:.35;cursor:default}",
 			".thm_yearLabel{color:var(--dsw-alias-label-secondary);font-size:11px;line-height:16px;min-width:36px;text-align:center;font-variant-numeric:tabular-nums}",
+			".thm_monthLabelNav{min-width:62px}",
+			".thm_viewNav{border:1px solid var(--dsw-alias-border-l2);border-radius:8px;align-items:center;display:inline-flex;overflow:hidden}",
+			".thm_viewBtn{cursor:pointer;color:var(--dsw-alias-label-tertiary);background:0 0;border:none;padding:1px 10px;font:inherit;font-size:11px;line-height:18px}",
+			".thm_viewBtn:hover:not(:disabled){color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-interactive-bg-hover)}",
+			".thm_viewBtn[data-active=true]{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover);font-weight:600}",
+			".thm_viewBtn:disabled{opacity:.4;cursor:default}",
 			".thm_refresh{cursor:pointer;color:var(--dsw-alias-label-tertiary);background:0 0;border:none;border-radius:6px;margin-left:auto;padding:2px 6px;font:inherit;font-size:11px;line-height:16px}",
 			".thm_refresh:hover{color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-interactive-bg-hover)}",
 			".thm_refresh:disabled{opacity:.5;cursor:default}",
@@ -60,49 +75,54 @@ window.__ModuleLoader__.load({
 			".thm_row{display:flex;gap:2px}",
 			".thm_rowLabel{color:var(--dsw-alias-label-caption);width:16px;flex:none;font-size:9px;line-height:12px;text-align:center}",
 			".thm_cell{box-sizing:border-box;width:10px;height:10px;border-radius:2px;flex:none}",
-			".thm_legend{align-items:center;gap:3px;margin-left:auto;font-size:10px;line-height:14px;display:inline-flex;color:var(--dsw-alias-label-tertiary)}",
-			".thm_legendCell{box-sizing:border-box;width:9px;height:9px;border-radius:2px}",
+			// The calendar spans the card's full content width, so the weekday
+			// rail (一) starts exactly under the "Token 用量" title.
+			".thm_monthCal{display:flex;flex-direction:column;gap:3px}",
+			".thm_weekHead{display:flex;gap:4px}",
+			".thm_weekHeadCell{color:var(--dsw-alias-label-tertiary);flex:1;min-width:0;font-size:9px;line-height:12px;text-align:center}",
+			".thm_week{display:flex;gap:4px}",
+			".thm_day{box-sizing:border-box;flex:1;min-width:0;height:38px;border-radius:5px;flex-direction:column;align-items:center;justify-content:center;gap:1px;display:flex}",
+			".thm_day[data-weekend=true]:not([data-empty=true]){background-color:var(--dsw-alias-interactive-bg-hover)}",
+			".thm_dayNum{color:var(--dsw-alias-label-secondary);font-size:11px;line-height:13px;font-variant-numeric:tabular-nums}",
+			".thm_dayTokens{color:var(--dsw-alias-label-tertiary);font-size:8px;line-height:10px;font-variant-numeric:tabular-nums}",
+			".thm_day[data-level=\"2\"] .thm_dayNum,.thm_day[data-level=\"3\"] .thm_dayNum,.thm_day[data-level=\"4\"] .thm_dayNum{color:#fff;text-shadow:0 1px 2px rgba(0,0,0,.28)}",
+			".thm_day[data-level=\"2\"] .thm_dayTokens,.thm_day[data-level=\"3\"] .thm_dayTokens,.thm_day[data-level=\"4\"] .thm_dayTokens{color:rgba(255,255,255,.82)}",
+			".thm_legend{align-items:center;justify-content:flex-end;gap:3px;font-size:10px;line-height:14px;display:flex;color:var(--dsw-alias-label-tertiary)}",			".thm_legendCell{box-sizing:border-box;width:9px;height:9px;border-radius:2px}",
 			".thm_error{color:var(--dsw-alias-state-error-primary);background:var(--dsw-alias-interactive-bg-hover-danger);border-radius:8px;padding:7px 8px;font-size:11px;line-height:16px;display:flex;justify-content:space-between;align-items:center;gap:8px}",
 			".thm_retry{color:inherit;font:inherit;cursor:pointer;background:0 0;border:none;flex:none;padding:0}",
 			".thm_loading{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px;padding:6px 2px}",
-			".thms_card{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);border-radius:12px;list-style:none;transition:border-color .16s,background .16s}",
-			".thms_card:hover{border-color:var(--dsw-alias-label-dimmed)}",
-			".thms_cardOpen{background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-label-dimmed)}",
-			".thms_header{appearance:none;width:100%;font:inherit;color:inherit;text-align:left;cursor:pointer;background:0 0;border:0;border-radius:12px;align-items:center;gap:12px;padding:14px 16px;display:flex}",
-			".thms_headText{flex-direction:column;flex:1;gap:4px;min-width:0;display:flex}",
-			".thms_name{color:var(--dsw-alias-label-primary);font-size:15px;font-weight:600;line-height:1.4}",
-			".thms_desc{color:var(--dsw-alias-label-tertiary);font-size:13px;line-height:1.5}",
-			".thms_chevron{color:var(--dsw-alias-label-tertiary);flex:none;transition:transform .16s}",
-			".thms_chevronOpen{transform:rotate(180deg)}",
-			".thms_pending{white-space:nowrap;background:var(--dsw-alias-bg-module-platform);color:var(--dsw-alias-label-secondary);border-radius:999px;flex:none;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px}",
-			".thms_body{border-top:1px solid var(--dsw-alias-border-l2);margin:0 16px;padding:12px 0 8px;display:flex;flex-direction:column;gap:12px}",
-			".thms_loading{color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:1.5;margin:0}",
-			".thms_error{color:var(--dsw-alias-label-error);font-size:12px;line-height:1.5;margin:0}",
-			".thms_retryBtn{color:inherit;font:inherit;cursor:pointer;background:0 0;border:none;flex:none;padding:0;text-decoration:underline}",
-			".thms_field{display:flex;flex-direction:column;gap:4px}",
-			".thms_fieldLabel{color:var(--dsw-alias-label-primary);font-size:13px;font-weight:500;line-height:1.5}",
-			".thms_fieldHint{color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:1.5;margin:0}",
-			".thms_switchRow{display:flex;align-items:center;gap:10px}",
-			".thms_switch{position:relative;width:36px;height:20px;flex:none;border-radius:999px;border:0;padding:0;cursor:pointer;background:var(--dsw-alias-interactive-bg-hover-solid);transition:background .15s}",
-			".thms_switch:disabled{opacity:.5;cursor:default}",
-			".thms_switchOn{background:var(--dsw-alias-state-business-primary)}",
-			".thms_thumb{position:absolute;top:2px;left:2px;width:16px;height:16px;border-radius:50%;background:#fff;box-shadow:0 1px 2px rgba(0,0,0,.25);transition:transform .15s}",
-			".thms_switchOn .thms_thumb{transform:translateX(16px)}",
-			".thms_swatches{display:flex;flex-wrap:wrap;gap:8px}",
-			".thms_swatch{appearance:none;font:inherit;cursor:pointer;align-items:center;gap:8px;border:1px solid var(--dsw-alias-border-l2);background:0 0;border-radius:8px;padding:6px 10px;display:flex}",
-			".thms_swatch:hover:not(:disabled){border-color:var(--dsw-alias-label-dimmed)}",
-			".thms_swatch:disabled{opacity:.5;cursor:default}",
-			".thms_swatch[data-active=true]{border-color:var(--dsw-alias-state-business-primary);box-shadow:0 0 0 1px var(--dsw-alias-state-business-primary) inset}",
-			".thms_swatchCells{display:flex;gap:2px}",
-			".thms_swatchCell{width:10px;height:10px;border-radius:2px}",
-			".thms_swatchLabel{color:var(--dsw-alias-label-secondary);font-size:12px;line-height:1.5}",
-			".thms_footer{border-top:1px solid var(--dsw-alias-border-l2);justify-content:flex-end;align-items:center;gap:8px;padding:12px 0 4px;display:flex}",
-			".thms_footerError{min-width:0;color:var(--dsw-alias-label-error);flex:1;margin:0;font-size:12px;line-height:1.5}",
-			".thms_btn{appearance:none;font:inherit;cursor:pointer;border:1px solid #0000;border-radius:8px;padding:5px 14px;font-size:13px;line-height:1.5}",
-			".thms_btn:disabled{opacity:.4;cursor:default}",
-			".thms_discard{border-color:var(--dsw-alias-border-l2);color:var(--dsw-alias-label-secondary);background:0 0}",
-			".thms_discard:hover:not(:disabled){color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-dimmed)}",
-			".thms_save{background:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-3)}"
+			// The ⚙ at the row's right end opens a floating pill panel — the
+			// card configures itself; nothing registers into 设置 → 插件 → 插件配置.
+			".thm_gear{cursor:pointer;color:var(--dsw-alias-label-tertiary);background:0 0;border:none;border-radius:6px;align-items:center;padding:2px 4px;display:inline-flex}",
+			".thm_gear:hover{color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-interactive-bg-hover)}",
+			".thm_gear[data-active=true]{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}",
+			// The settings panel mirrors DSH's own pill dialogs: portaled to
+			// document.body, position:fixed (so the card can never clip it),
+			// measure-then-place above the ⚙ and clamped to the viewport, with
+			// the shipped dialog surface + elevation tokens.
+			".thm_panel{position:fixed;z-index:1100;box-sizing:border-box;background:var(--dsw-specific-menu,#fff);--dsw-elevation-stroke-color:var(--dsw-alias-border-l1);width:400px;max-width:calc(100vw - 24px);box-shadow:var(--dsw-elevation-prominent,0 8px 32px rgba(0,0,0,.16));color:var(--dsw-alias-label-secondary);cursor:default;border:0;border-radius:12px;padding:16px;font-size:12px;line-height:18px;text-align:left;font-weight:400}",
+			".thm_panelHead{color:var(--dsw-alias-label-primary);justify-content:space-between;align-items:center;gap:16px;margin-bottom:8px;font-weight:500;display:flex}",
+			".thm_panelTitleLabel{align-items:center;gap:6px;display:inline-flex}",
+			".thm_panelTitleLabel svg{flex:none;width:14px;height:14px}",
+			".thm_panelRule{border-top:.5px solid var(--dsw-alias-border-l2);margin-bottom:12px}",
+			".thm_group{flex-direction:column;gap:5px;display:flex}",
+			".thm_group+.thm_group{margin-top:14px}",
+			".thm_groupLabel{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px}",
+			".thm_swatches{flex-wrap:wrap;gap:6px;display:flex}",
+			".thm_swatch{cursor:pointer;align-items:center;gap:6px;border:1px solid var(--dsw-alias-border-l2);background:0 0;border-radius:6px;padding:3px 8px;font:inherit;display:flex}",
+			".thm_swatch:hover{border-color:var(--dsw-alias-label-dimmed)}",
+			".thm_swatch[data-active=true]{border-color:var(--dsw-alias-state-business-primary);box-shadow:0 0 0 1px var(--dsw-alias-state-business-primary) inset}",
+			".thm_swatchCells{display:flex;gap:2px}",
+			".thm_swatchCell{width:9px;height:9px;border-radius:2px}",
+			".thm_swatchLabel{color:var(--dsw-alias-label-secondary);font-size:11px;line-height:16px}",
+			".thm_seg{border:1px solid var(--dsw-alias-border-l2);border-radius:8px;align-items:center;display:inline-flex;overflow:hidden;width:max-content}",
+			".thm_segBtn{cursor:pointer;color:var(--dsw-alias-label-tertiary);background:0 0;border:none;padding:1px 10px;font:inherit;font-size:11px;line-height:18px}",
+			".thm_segBtn:hover{color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-interactive-bg-hover)}",
+			".thm_segBtn[data-active=true]{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover);font-weight:600}",
+			".thm_panelFoot{border-top:.5px solid var(--dsw-alias-border-l2);margin-top:14px;padding-top:10px}",
+			".thm_footLegend{align-items:center;gap:3px;font-size:10px;line-height:14px;display:flex;color:var(--dsw-alias-label-tertiary)}",
+			".thm_footRule{color:var(--dsw-alias-label-caption);margin-top:6px;font-size:10px;line-height:14px}",
+			".thm_footError{color:var(--dsw-alias-state-error-primary);margin-top:6px;font-size:10px;line-height:14px}"
 		].join("");
 		const tagId = "@kidli1412/dsh-token-heatmap/TokenHeatmap.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
@@ -120,9 +140,12 @@ window.__ModuleLoader__.load({
 			stat: "thm_stat",
 			statLabel: "thm_statLabel",
 			statValue: "thm_statValue",
-			yearNav: "thm_yearNav",
+			nav: "thm_nav",
 			yearBtn: "thm_yearBtn",
 			yearLabel: "thm_yearLabel",
+			monthLabelNav: "thm_monthLabelNav",
+			viewNav: "thm_viewNav",
+			viewBtn: "thm_viewBtn",
 			refresh: "thm_refresh",
 			gridWrap: "thm_gridWrap",
 			grid: "thm_grid",
@@ -131,41 +154,36 @@ window.__ModuleLoader__.load({
 			row: "thm_row",
 			rowLabel: "thm_rowLabel",
 			cell: "thm_cell",
+			monthCal: "thm_monthCal",
+			weekHead: "thm_weekHead",
+			weekHeadCell: "thm_weekHeadCell",
+			week: "thm_week",
+			day: "thm_day",
+			dayNum: "thm_dayNum",
+			dayTokens: "thm_dayTokens",
 			legend: "thm_legend",
 			legendCell: "thm_legendCell",
 			error: "thm_error",
 			retry: "thm_retry",
 			loading: "thm_loading",
-			settingsCard: "thms_card",
-			settingsCardOpen: "thms_cardOpen",
-			settingsHeader: "thms_header",
-			settingsHeadText: "thms_headText",
-			settingsName: "thms_name",
-			settingsDesc: "thms_desc",
-			settingsChevron: "thms_chevron",
-			settingsChevronOpen: "thms_chevronOpen",
-			settingsPending: "thms_pending",
-			settingsBody: "thms_body",
-			settingsLoading: "thms_loading",
-			settingsError: "thms_error",
-			settingsRetry: "thms_retryBtn",
-			settingsField: "thms_field",
-			settingsFieldLabel: "thms_fieldLabel",
-			settingsFieldHint: "thms_fieldHint",
-			settingsSwitchRow: "thms_switchRow",
-			settingsSwitch: "thms_switch",
-			settingsSwitchOn: "thms_switchOn",
-			settingsThumb: "thms_thumb",
-			settingsSwatches: "thms_swatches",
-			settingsSwatch: "thms_swatch",
-			settingsSwatchCells: "thms_swatchCells",
-			settingsSwatchCell: "thms_swatchCell",
-			settingsSwatchLabel: "thms_swatchLabel",
-			settingsFooter: "thms_footer",
-			settingsFooterError: "thms_footerError",
-			settingsBtn: "thms_btn",
-			settingsDiscard: "thms_discard",
-			settingsSave: "thms_save"
+			gear: "thm_gear",
+			settingsPanel: "thm_panel",
+			panelHead: "thm_panelHead",
+			panelTitleLabel: "thm_panelTitleLabel",
+			panelRule: "thm_panelRule",
+			panelFoot: "thm_panelFoot",
+			footLegend: "thm_footLegend",
+			footRule: "thm_footRule",
+			footError: "thm_footError",
+			settingsGroup: "thm_group",
+			settingsGroupLabel: "thm_groupLabel",
+			settingsSwatches: "thm_swatches",
+			settingsSwatch: "thm_swatch",
+			settingsSwatchCells: "thm_swatchCells",
+			settingsSwatchCell: "thm_swatchCell",
+			settingsSwatchLabel: "thm_swatchLabel",
+			seg: "thm_seg",
+			segBtn: "thm_segBtn"
 		};
 		//#endregion
 
@@ -184,31 +202,32 @@ window.__ModuleLoader__.load({
 			total: "累计",
 			prevYear: "上一年",
 			nextYear: "下一年",
+			prevMonth: "上一月",
+			nextMonth: "下一月",
+			viewYear: "年",
+			viewMonth: "月",
+			viewLabel: "视图",
 			less: "少",
 			more: "多",
 			cellTokens: "{date} · {tokens} tokens",
 			weekdayLabel: ["一", "二", "三", "四", "五", "六", "日"],
 			monthName: ["1月", "2月", "3月", "4月", "5月", "6月", "7月", "8月", "9月", "10月", "11月", "12月"],
+			dayLabel: (monthName, day) => `${monthName}${day}日`,
+			monthYear: (year, monthName) => `${year}年${monthName}`,
 			levelLegend: ["0", "<1M", "1M–10M", "10M–100M", "≥100M"],
 			settingsTitle: "Token 用量热力图",
-			settingsDescription: "新会话页面的 Token 用量热力图显示与配色。",
-			settingsEnabled: "显示热力图",
-			settingsEnabledHint: "关闭后，新会话输入框下方的 Token 用量热力图不再显示。",
 			settingsScheme: "配色方案",
 			settingsSchemeHint: "热力图格子的颜色主题：绿色为经典 GitHub 风格，其余为新增配色。",
+			settingsDefaultView: "默认视图",
+			settingsDefaultViewHint: "新会话页面首次打开时显示的视图（标题行右端可随时切换）。",
 			settingsGreen: "绿色",
 			settingsBlue: "蓝色",
 			settingsOrange: "橙色",
 			settingsRed: "红色",
 			settingsPurple: "紫色",
 			settingsTeal: "青色",
-			settingsSave: "保存",
-			settingsSaving: "保存中…",
-			settingsDiscard: "放弃修改",
-			settingsUnsaved: "未保存",
-			settingsSaveFailed: "保存失败，修改已保留，请重试。",
-			settingsLoadFailed: "配置加载失败。",
-			settingsRetry: "重试",
+			settingsThresholdNote: "颜色按每天 token 数的绝对阈值分档（悬停图例看各档范围）。",
+			settingsSaveFailed: "保存失败，已回到服务端的值，请重试。",
 			settingsExpand: "展开设置",
 			settingsCollapse: "收起设置"
 		};
@@ -224,31 +243,32 @@ window.__ModuleLoader__.load({
 			total: "All time",
 			prevYear: "Previous year",
 			nextYear: "Next year",
+			prevMonth: "Previous month",
+			nextMonth: "Next month",
+			viewYear: "Year",
+			viewMonth: "Month",
+			viewLabel: "View",
 			less: "Less",
 			more: "More",
 			cellTokens: "{date} · {tokens} tokens",
 			weekdayLabel: ["M", "T", "W", "T", "F", "S", "S"],
 			monthName: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
+			dayLabel: (monthName, day) => `${monthName} ${day}`,
+			monthYear: (year, monthName) => `${monthName} ${year}`,
 			levelLegend: ["0", "<1M", "1M–10M", "10M–100M", "≥100M"],
 			settingsTitle: "Token usage heatmap",
-			settingsDescription: "Display and colors of the token heatmap on the new-session screen.",
-			settingsEnabled: "Show heatmap",
-			settingsEnabledHint: "When off, the token heatmap below the composer is hidden.",
 			settingsScheme: "Color scheme",
 			settingsSchemeHint: "Cell palette: green is the classic GitHub style; the rest are new themes.",
+			settingsDefaultView: "Default view",
+			settingsDefaultViewHint: "The view the new-session screen opens with (switchable anytime at the row's right end).",
 			settingsGreen: "Green",
 			settingsBlue: "Blue",
 			settingsOrange: "Orange",
 			settingsRed: "Red",
 			settingsPurple: "Purple",
 			settingsTeal: "Teal",
-			settingsSave: "Save",
-			settingsSaving: "Saving…",
-			settingsDiscard: "Discard",
-			settingsUnsaved: "Unsaved",
-			settingsSaveFailed: "Save failed; your changes were kept.",
-			settingsLoadFailed: "Failed to load configuration.",
-			settingsRetry: "Retry",
+			settingsThresholdNote: "Colors follow absolute per-day token thresholds (hover the legend for each range).",
+			settingsSaveFailed: "Save failed; the server value was restored.",
 			settingsExpand: "Show settings",
 			settingsCollapse: "Hide settings"
 		};
@@ -293,6 +313,19 @@ window.__ModuleLoader__.load({
 			return key.slice(0, 7);
 		}
 
+		/**
+		 * Step a `YYYY-MM` key by whole months ("2026-01" -1 → "2025-12"),
+		 * returning the input unchanged when it is not a month key.
+		 * @param key - `YYYY-MM` month key.
+		 * @param delta - signed month count.
+		 */
+		function shiftMonthKey(key, delta) {
+			const [year, month] = key.split("-").map(Number);
+			if (!Number.isFinite(year) || !Number.isFinite(month)) return key;
+			const date = new Date(year, month - 1 + delta, 1);
+			return monthKey(date.getTime());
+		}
+
 		/**
 		 * Pick the display dictionary for locale-shaped helpers (month names,
 		 * weekday labels, date formatting). The locale plugin resolves the UI
@@ -305,13 +338,31 @@ window.__ModuleLoader__.load({
 			return candidates.some((tag) => tag.toLowerCase().startsWith("zh")) ? zh : en;
 		}
 
-		/** Display date "8月13日" / "Aug 13". */
+		/**
+		 * Display date "8月13日" / "Aug 13" — the whole shape comes from the
+		 * dictionary, so an English UI never renders a Chinese 日 and the
+		 * Chinese one never grows a space before it.
+		 */
 		function dateLabel(key) {
 			const [year, month, day] = key.split("-").map(Number);
-			const names = uiDict().monthName;
-			return `${names[month - 1]} ${day}日`;
+			const dict = uiDict();
+			return dict.dayLabel(dict.monthName[month - 1], day);
+		}
+
+		/**
+		 * Month-key navigation label, ordered per locale: "2026年8月" in Chinese
+		 * (year first), "Aug 2026" in English (month first) — each dictionary
+		 * owns its ordering rather than both sharing a Chinese-shaped template.
+		 */
+		function monthLabelFull(key) {
+			const [year, month] = key.split("-").map(Number);
+			const dict = uiDict();
+			return dict.monthYear(year, dict.monthName[month - 1]);
 		}
 
+		/** Heatmap view modes: the calendar-year grid or a single-month calendar. */
+		const VIEW_MODES = ["year", "month"];
+
 		/** Per-request staleness guard: only the most recent start may `isCurrent()`. */
 		function createLoader() {
 			let current = 0;
@@ -332,25 +383,32 @@ window.__ModuleLoader__.load({
 
 		//#region config store (settings-scope backed)
 		/**
-		 * Display preferences (enabled + colorScheme), persisted through the
-		 * Host `token-heatmap` settings namespace (settings.yaml) via the bound
-		 * settings scope — NOT the legacy loopback config endpoint. The
+		 * Display preferences (colorScheme + defaultView), persisted through
+		 * the Host `token-heatmap` settings namespace (settings.yaml) via the
+		 * bound settings scope — NOT the legacy loopback config endpoint. The
 		 * heatmap and the settings card read the store through
 		 * useSyncExternalStore; while the scope is loading or unavailable the
-		 * store falls back to the defaults (enabled / green), so the UI never
-		 * blocks on the settings transport.
+		 * store falls back to the defaults (green / year view), so the UI never
+		 * blocks on the settings transport. The 0.1.x display switch is gone:
+		 * its `enabled` key is simply no longer read (see the settings card).
 		 */
-		const CONFIG_DEFAULTS = { enabled: true, colorScheme: "green" };
+		const CONFIG_DEFAULTS = { colorScheme: "green", defaultView: "year" };
 		/** Coerce a scheme to a non-blank string, else the default. */
 		function sanitizeScheme(value) {
 			if (typeof value !== "string") return CONFIG_DEFAULTS.colorScheme;
 			const scheme = value.trim();
 			return scheme.length > 0 && scheme.length <= 32 ? scheme : CONFIG_DEFAULTS.colorScheme;
 		}
+		/** Coerce a view mode to a known mode, else the default (year). */
+		function sanitizeView(value) {
+			if (typeof value !== "string") return CONFIG_DEFAULTS.defaultView;
+			const view = value.trim();
+			return VIEW_MODES.includes(view) ? view : CONFIG_DEFAULTS.defaultView;
+		}
 		/**
 		 * Reactive adapter over one bound settings scope: a
 		 * useSyncExternalStore-compatible store whose snapshot is
-		 * `{ status, enabled, colorScheme }` derived from the scope.
+		 * `{ status, colorScheme, defaultView }` derived from the scope.
 		 * `set(patch)` writes the touched fields through scope.set (async; the
 		 * scope fences revisions and reloads on failure), and the snapshot
 		 * only changes after the Host confirms. `reload()` re-reads from the
@@ -367,8 +425,8 @@ window.__ModuleLoader__.load({
 				const v = s.value;
 				return {
 					status: s.status,
-					enabled: v.enabled !== false,
-					colorScheme: sanitizeScheme(v.colorScheme)
+					colorScheme: sanitizeScheme(v.colorScheme),
+					defaultView: sanitizeView(v.defaultView)
 				};
 			};
 			const notify = () => {
@@ -389,12 +447,12 @@ window.__ModuleLoader__.load({
 					};
 				},
 				set: async (patch) => {
-					if (Object.hasOwn(patch, "enabled")) {
-						await scope.set("enabled", patch.enabled === true);
-					}
 					if (Object.hasOwn(patch, "colorScheme")) {
 						await scope.set("colorScheme", sanitizeScheme(patch.colorScheme));
 					}
+					if (Object.hasOwn(patch, "defaultView")) {
+						await scope.set("defaultView", sanitizeView(patch.defaultView));
+					}
 				},
 				reload: () => scope.load(),
 				dispose: () => unsubscribe()
@@ -490,13 +548,56 @@ window.__ModuleLoader__.load({
 			}
 			return { columns, monthStarts };
 		}
+
+		/**
+		 * Build the calendar grid for ONE MONTH (the 年/月 view switch's month
+		 * view): Monday-first weeks, exactly as many week rows as the month
+		 * spans (5 or 6), cells outside the month null. Days after today are
+		 * empty level-0 cells (today itself is always rendered with its real
+		 * value), and every cell carries `day` (day of month) so the calendar
+		 * can print numbers on top of the same absolute-threshold heat colors
+		 * the year view uses.
+		 * @param dayMap - date key → tokens.
+		 * @param now - reference timestamp.
+		 * @param month - `YYYY-MM` to render; defaults to the month of `now`.
+		 * @returns `{ month, weeks, weekdays }` where each week is
+		 *   `Array<{key, tokens, level, day} | null>` of 7 cells.
+		 */
+		function buildMonthGrid(dayMap, now, month) {
+			const nowDate = new Date(now);
+			const todayKey = dayKey(nowDate.getTime());
+			const target = month ?? monthKey(nowDate.getTime());
+			const [year, monthNumber] = target.split("-").map(Number);
+			const monthStart = new Date(year, monthNumber - 1, 1);
+			const monthEnd = new Date(year, monthNumber, 0);
+			const startKey = dayKey(monthStart.getTime());
+			const endKey = dayKey(monthEnd.getTime());
+			const cursor = new Date(year, monthNumber - 1, 1 - ((monthStart.getDay() + 6) % 7));
+			const weeks = [];
+			while (cursor.getTime() <= monthEnd.getTime()) {
+				const cells = [];
+				for (let d = 0; d < 7; d += 1) {
+					const key = dayKey(cursor.getTime());
+					if (key < startKey || key > endKey) {
+						cells.push(null);
+					} else {
+						const future = key > todayKey;
+						const tokens = future ? 0 : (dayMap.get(key) ?? 0);
+						cells.push({ key, tokens, level: levelOf(tokens), day: cursor.getDate() });
+					}
+					cursor.setDate(cursor.getDate() + 1);
+				}
+				weeks.push(cells);
+			}
+			return { month: target, weeks, weekdays: 7 };
+		}
 		//#endregion
 
 		//#region TokenHeatmap
 		/**
 		 * The heatmap card. Shown only on the new-session hero screen
-		 * (`composerPhase === "blank"`); a flex `order` on the wrapper places
-		 * it below the composer input card.
+		 * (`session.blank`, or `composerPhase === "blank"` on older hosts); a
+		 * flex `order` on the wrapper places it below the composer input card.
 		 * @param props - `session`/`input` from the InputZone owner share, `t`
 		 *   bound by the slot runtime locale seat.
 		 */
@@ -507,6 +608,38 @@ window.__ModuleLoader__.load({
 			const [error, setError] = react.useState(null);
 			const [loading, setLoading] = react.useState(false);
 			const [year, setYear] = react.useState(() => new Date().getFullYear());
+			// Active view mode, seeded from the persisted default (the 年/月
+			// switch at the row's right end; a manual switch wins for this
+			// mount).
+			const [view, setView] = react.useState(() => sanitizeView(configStore?.getSnapshot().defaultView));
+			// Month-view cursor (`YYYY-MM`); initialised from the current month
+			// and re-anchored when it would fall outside the navigable bounds.
+			const [monthCursor, setMonthCursor] = react.useState(() => monthKey(Date.now()));
+			// The ⚙ at the row's right end opens the floating settings panel;
+			// the card configures itself here instead of living in
+			// 设置 → 插件 → 插件配置. The panel is PORTALED to document.body and
+			// anchored to this button, so the open state lives here with it.
+			const gearRef = react.useRef(null);
+			const [settingsOpen, setSettingsOpen] = react.useState(false);
+			react.useEffect(() => {
+				if (!settingsOpen) return;
+				const onKeyDown = (event) => {
+					if (event.key === "Escape") setSettingsOpen(false);
+				};
+				const onPointerDown = (event) => {
+					const gear = gearRef.current;
+					if (gear !== null && gear.contains(event.target)) return;
+					const panel = document.querySelector(`.${S.settingsPanel}`);
+					if (panel !== null && panel.contains(event.target)) return;
+					setSettingsOpen(false);
+				};
+				document.addEventListener("keydown", onKeyDown);
+				document.addEventListener("pointerdown", onPointerDown, true);
+				return () => {
+					document.removeEventListener("keydown", onKeyDown);
+					document.removeEventListener("pointerdown", onPointerDown, true);
+				};
+			}, [settingsOpen]);
 			const loaderRef = react.useRef(null);
 			if (loaderRef.current === null) loaderRef.current = createLoader();
 			const load = react.useCallback(async () => {
@@ -545,17 +678,18 @@ window.__ModuleLoader__.load({
 			// New-session hero only. DSH 0.1.2+ (rc.1) exposes the state as
 			// the boolean `session.blank` (the `composerPhase` string is
 			// gone); older harnesses keep `composerPhase === "blank"`.
-			// Conversed sessions hide the card.
+			// Conversed sessions hide the card. There is no display switch any
+			// more: the card is always shown on the hero screen, and the
+			// settings card only carries presentation choices.
 			if (session === void 0 || session === null || input === void 0 || input === null) return null;
 			const heroBlank = typeof session.blank === "boolean" ? session.blank === true : session.composerPhase === "blank";
 			if (!heroBlank) return null;
-			// Master switch from the settings card (设置 → 插件 → 插件配置).
-			if (config.enabled === false) return null;
 
 			const now = Date.now();
-			// Year-selector bounds: the current year at most (no future usage),
-			// and at least the earliest year present in the data so the selector
-			// cannot wander into guaranteed-empty territory.
+			// Navigation bounds, derived from the data itself: at most the
+			// current year/month (future usage cannot exist) and at least the
+			// earliest one present, so the ‹ › selectors never wander into
+			// guaranteed-empty territory.
 			const nowYear = new Date(now).getFullYear();
 			let minYear = nowYear;
 			for (const day of data?.days ?? []) {
@@ -563,21 +697,47 @@ window.__ModuleLoader__.load({
 				if (y < minYear) minYear = y;
 			}
 			const maxYear = nowYear;
+			const currentMonthKey = monthKey(now);
+			let minMonth = currentMonthKey;
+			for (const day of data?.days ?? []) {
+				const key = monthOfDateKey(day.date);
+				if (key < minMonth) minMonth = key;
+			}
+			const maxMonth = currentMonthKey;
 			const todayTokens = data?.days?.find((day) => day.date === dayKey(now))?.tokens ?? 0;
-			const monthPrefix = monthKey(now);
+			const monthPrefix = currentMonthKey;
 			let monthTokens = 0;
 			for (const day of data?.days ?? []) {
 				if (day.date.startsWith(monthPrefix)) monthTokens += day.tokens;
 			}
 			const totalTokens = data?.total ?? 0;
+			// Keep the last known cursor, but never outside the bounds (a
+			// brand-new store of only old months must not open on next month).
+			const activeMonth = monthCursor < minMonth
+				? minMonth
+				: monthCursor > maxMonth ? maxMonth : monthCursor;
 
 			const dayMap = new Map();
 			for (const day of data?.days ?? []) dayMap.set(day.date, day.tokens);
 			const grid = buildGrid(dayMap, now, year);
+			const monthGrid = buildMonthGrid(dayMap, now, activeMonth);
 			const levelLegend = uiDict().levelLegend;
-			// Palette from the settings card; unknown schemes fall back to green.
+			// Palette from the in-card settings panel; unknown schemes fall back
+			// to green.
 			const palette = COLOR_SCHEMES[config.colorScheme] ?? COLOR_SCHEMES.green;
 
+			// ‹ › step the active view: years in year view, months in month view.
+			const stepBack = () => {
+				if (view === "month") setMonthCursor(shiftMonthKey(activeMonth, -1));
+				else setYear(year - 1);
+			};
+			const stepForward = () => {
+				if (view === "month") setMonthCursor(shiftMonthKey(activeMonth, 1));
+				else setYear(year + 1);
+			};
+			const backDisabled = view === "month" ? activeMonth <= minMonth : year <= minYear;
+			const forwardDisabled = view === "month" ? activeMonth >= maxMonth : year >= maxYear;
+
 			const stats = [
 				{ label: dict("today"), value: todayTokens },
 				{ label: dict("month"), value: monthTokens },
@@ -622,37 +782,123 @@ window.__ModuleLoader__.load({
 									]
 								}, stat.label)),
 								react_jsx_runtime.jsxs("span", {
-									className: S.yearNav,
+									className: S.nav,
 									children: [
 										react_jsx_runtime.jsx("button", {
 											type: "button",
 											className: S.yearBtn,
-											disabled: year <= minYear,
-											onClick: () => setYear(year - 1),
-											"aria-label": dict("prevYear"),
+											disabled: backDisabled,
+											onClick: stepBack,
+											"aria-label": dict(view === "month" ? "prevMonth" : "prevYear"),
 											children: "\u2039"
 										}),
-										react_jsx_runtime.jsx("span", { className: S.yearLabel, children: String(year) }),
+										view === "month" ? react_jsx_runtime.jsx("span", {
+											className: `${S.yearLabel} ${S.monthLabelNav}`,
+											children: monthLabelFull(activeMonth)
+										}) : react_jsx_runtime.jsx("span", { className: S.yearLabel, children: String(year) }),
 										react_jsx_runtime.jsx("button", {
 											type: "button",
 											className: S.yearBtn,
-											disabled: year >= maxYear,
-											onClick: () => setYear(year + 1),
-											"aria-label": dict("nextYear"),
+											disabled: forwardDisabled,
+											onClick: stepForward,
+											"aria-label": dict(view === "month" ? "nextMonth" : "nextYear"),
 											children: "\u203a"
 										})
 									]
 								}),
+								// The view switch sits next to the ‹ › stepper it pairs
+								// with; the ⚙ closes the row on the right.
+								react_jsx_runtime.jsx("span", {
+									className: S.viewNav,
+									role: "group",
+									"aria-label": dict("viewLabel"),
+									children: VIEW_MODES.map((mode) => react_jsx_runtime.jsx("button", {
+										type: "button",
+										className: S.viewBtn,
+										"data-active": view === mode,
+										"aria-pressed": view === mode,
+										onClick: () => setView(mode),
+										children: dict(mode === "month" ? "viewMonth" : "viewYear")
+									}, mode))
+								}),
 								react_jsx_runtime.jsx("button", {
 									type: "button",
 									className: S.refresh,
 									disabled: loading,
 									onClick: load,
 									children: dict("refresh")
+								}),
+								// The ⚙ owns the row's right end; the ‹ › stepper
+								// and the view switch sit left of it, the stepper
+								// next to the stats it moves through. This button is
+								// also the settings panel's anchor.
+								react_jsx_runtime.jsx("button", {
+									type: "button",
+									ref: gearRef,
+									className: S.gear,
+									"data-active": settingsOpen,
+									"aria-haspopup": "dialog",
+									"aria-expanded": settingsOpen,
+									"aria-label": dict(settingsOpen ? "settingsCollapse" : "settingsExpand"),
+									title: dict(settingsOpen ? "settingsCollapse" : "settingsExpand"),
+									onClick: () => setSettingsOpen(!settingsOpen),
+									children: react_jsx_runtime.jsx("svg", {
+										width: 14,
+										height: 14,
+										viewBox: "0 0 24 24",
+										fill: "none",
+										stroke: "currentColor",
+										"aria-hidden": "true",
+										children: react_jsx_runtime.jsx("path", {
+											d: "M10.9 2.6h2.2l.4 2.5 1.9.8 2-1.5 1.6 1.6-1.5 2 .8 1.9 2.5.4v2.2l-2.5.4-.8 1.9 1.5 2-1.6 1.6-2-1.5-1.9.8-.4 2.5h-2.2l-.4-2.5-1.9-.8-2 1.5-1.6-1.6 1.5-2-.8-1.9-2.5-.4v-2.2l2.5-.4.8-1.9-1.5-2 1.6-1.6 2 1.5 1.9-.8.4-2.5Z",
+											"stroke-width": 1.5,
+											"stroke-linejoin": "round",
+											"stroke-linecap": "round"
+										})
+									})
 								})
 							]
 						}),
-						react_jsx_runtime.jsx("div", {
+						view === "month" ? react_jsx_runtime.jsx("div", {
+							className: S.gridWrap,
+							children: react_jsx_runtime.jsxs("div", {
+								className: S.monthCal,
+								children: [
+									react_jsx_runtime.jsx("div", {
+										className: S.weekHead,
+										children: uiDict().weekdayLabel.map((label, index) => react_jsx_runtime.jsx("span", {
+											className: S.weekHeadCell,
+											children: label
+										}, `weekhead-${index}`))
+									}),
+									...monthGrid.weeks.map((week, weekIndex) => react_jsx_runtime.jsx("div", {
+										className: S.week,
+										children: week.map((cell, dayIndex) => {
+											if (cell === null) {
+												return react_jsx_runtime.jsx("span", {
+													className: S.day,
+													"data-empty": "true"
+												}, `empty-${weekIndex}-${dayIndex}`);
+											}
+											return react_jsx_runtime.jsxs("span", {
+												className: S.day,
+												"data-level": String(cell.level),
+												"data-weekend": dayIndex >= 5 ? "true" : "false",
+												style: { background: palette[cell.level] },
+												title: translate("cellTokens", { date: dateLabel(cell.key), tokens: fmt(cell.tokens) }),
+												children: [
+													react_jsx_runtime.jsx("span", { className: S.dayNum, children: String(cell.day) }),
+													cell.tokens > 0 ? react_jsx_runtime.jsx("span", {
+														className: S.dayTokens,
+														children: fmtCompact(cell.tokens)
+													}) : null
+												]
+											}, cell.key);
+										})
+									}, `week-${weekIndex}`))
+								]
+							})
+						}) : react_jsx_runtime.jsx("div", {
 							className: S.gridWrap,
 							children: react_jsx_runtime.jsxs("div", {
 								className: S.grid,
@@ -691,28 +937,32 @@ window.__ModuleLoader__.load({
 												})
 											]
 										}, `row-${row}`);
-									}),
-									react_jsx_runtime.jsx("div", {
-										className: S.row,
-										children: [
-											react_jsx_runtime.jsx("span", { className: S.rowLabel, children: "" }),
-											react_jsx_runtime.jsx("span", {
-												className: S.legend,
-												children: [
-													dict("less"),
-													...palette.map((color, level) => react_jsx_runtime.jsx("span", {
-														className: S.legendCell,
-														style: { background: color },
-														title: levelLegend[level] ?? ""
-													}, `lvl-${level}`)),
-													dict("more")
-												]
-											})
-										]
 									})
 								]
 							})
-						})
+						}),
+						react_jsx_runtime.jsx("div", {
+							className: S.legend,
+							children: [
+								dict("less"),
+								...palette.map((color, level) => react_jsx_runtime.jsx("span", {
+									className: S.legendCell,
+									style: { background: color },
+									title: levelLegend[level] ?? ""
+								}, `lvl-${level}`)),
+								dict("more")
+							]
+						}),
+						settingsOpen ? react_jsx_runtime.jsx(TokenHeatmapInlineSettings, {
+							dict,
+							config,
+							store: configStore,
+							palette,
+							translate,
+							legend: levelLegend,
+							anchor: gearRef.current,
+							onClose: () => setSettingsOpen(false)
+						}) : null
 					]
 				});
 			}
@@ -725,242 +975,245 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 
-		//#region TokenHeatmapSettingsCard
+		//#region TokenHeatmapInlineSettings
+		/** Distance between the ⚙ and the panel's bottom edge (native dialog spec). */
+		const PANEL_GAP = 8;
+		/** Viewport margin the placement clamp keeps (native dialog spec). */
+		const PANEL_MARGIN = 12;
+
 		/**
-		 * The plugin settings card, rendered inside the official
-		 * 设置 → 插件 → 插件配置 tab (the `settings.plugin.item` seat).
+		 * Place the floating panel above its ⚙ trigger, clamped to the viewport —
+		 * the same measure-then-place flow (and the same 8px gap / 12px margin)
+		 * the built-in stat dialogs use. The panel is `position:fixed` and lives
+		 * in `document.body`, so the card can never clip it.
+		 * @param trigger - the ⚙ button the panel is anchored to.
+		 * @param panel - the `position:fixed` panel element.
+		 */
+		function placePanel(trigger, panel) {
+			const anchor = trigger.getBoundingClientRect();
+			const width = panel.offsetWidth;
+			const height = panel.offsetHeight;
+			if (width === 0 || height === 0) return;
+			const viewportWidth = window.innerWidth;
+			const viewportHeight = window.innerHeight;
+			const left = Math.min(
+				Math.max(PANEL_MARGIN, anchor.left + anchor.width / 2 - width / 2),
+				Math.max(PANEL_MARGIN, viewportWidth - width - PANEL_MARGIN)
+			);
+			let top = anchor.top - height - PANEL_GAP;
+			if (top < PANEL_MARGIN) top = Math.min(anchor.bottom + PANEL_GAP, viewportHeight - height - PANEL_MARGIN);
+			panel.style.left = `${Math.round(left)}px`;
+			panel.style.top = `${Math.round(Math.max(PANEL_MARGIN, top))}px`;
+			panel.style.visibility = "visible";
+		}
+
+		/**
+		 * The card's settings panel: 配色方案 and 默认视图, edited from the card
+		 * itself instead of inside 设置 → 插件 → 插件配置 (this plugin no longer
+		 * registers into the `settings.plugin.item` seat).
+		 *
+		 * It is PORTALED to `document.body` (the card's own box can never clip
+		 * it) and anchored to the ⚙ through `anchor`; the owner closes it on
+		 * outside pointerdown and Escape, so this component only draws.
 		 *
-		 * The card edits the `token-heatmap` settings namespace through the
-		 * bound settings scope (the tab only dispatches it while the Host
-		 * serves that namespace) and stages a draft until the user saves,
-		 * mirroring the official card chrome (disclosure header, unsaved
-		 * badge, discard/save footer). The legacy loopback config endpoint
-		 * remains as a back-compat API, but the card no longer uses it.
-		 * @param props - `t` bound by the slot runtime locale seat.
+		 * Every control applies immediately through the bound settings scope —
+		 * there is no draft/save step, so the component owns only a local save
+		 * error. The 0.1.x 显示热力图 switch is gone (the card is always shown on
+		 * the hero screen), so its stored `enabled` key is neither read nor
+		 * written. The legacy loopback config endpoint remains as a back-compat
+		 * API, but nothing in the UI uses it.
+		 * @param props.dict - bound translator.
+		 * @param props.config - current config store snapshot.
+		 * @param props.store - config store (set writes through the scope).
+		 * @param props.palette - active palette (level 0..4 → css color).
+		 * @param props.translate - interpolation helper for translated labels.
+		 * @param props.legend - level labels for the palette footnote.
+		 * @param props.anchor - the ⚙ button the panel is placed against.
+		 * @param props.onClose - collapse the panel.
 		 */
-		function TokenHeatmapSettingsCard({ t }) {
-			const dict = t !== void 0 ? t : (key) => zh[key] ?? key;
-			const [open, setOpen] = react.useState(false);
-			const [loaded, setLoaded] = react.useState(null);
-			const [draft, setDraft] = react.useState(null);
-			const [saving, setSaving] = react.useState(false);
+		function TokenHeatmapInlineSettings({ dict, config, store, palette, translate, legend, anchor, onClose }) {
+			const panelRef = react.useRef(null);
 			const [saveFailed, setSaveFailed] = react.useState(false);
-			const config = react.useSyncExternalStore(configStore.subscribe, configStore.getSnapshot);
-			// Seed the staged form from the confirmed scope snapshot once (a
-			// later scope change is the card's own save confirmation; external
-			// edits land in loaded via the explicit sync in save()).
+			const schemes = Object.keys(COLOR_SCHEMES);
+			// Optimistic local echo: the settings scope only reports the new value
+			// after the Host confirms, and a control must not lag behind the click.
+			const [pending, setPending] = react.useState({});
+			const scheme = pending.colorScheme ?? config.colorScheme;
+			const defaultView = pending.defaultView ?? config.defaultView;
+			// Place before paint (and again when the palette reflows the panel):
+			// the trigger's box is only meaningful once the card is laid out.
+			react.useLayoutEffect(() => {
+				const panel = panelRef.current;
+				if (panel === null || anchor === null || anchor === void 0) return;
+				placePanel(anchor, panel);
+			});
 			react.useEffect(() => {
-				if (config.status !== "ready" || loaded !== null) return;
-				setLoaded({ enabled: config.enabled, colorScheme: config.colorScheme });
-				setDraft({ enabled: config.enabled, colorScheme: config.colorScheme });
-			}, [config, loaded]);
-
-			const dirty = loaded !== null && draft !== null && (draft.enabled !== loaded.enabled || draft.colorScheme !== loaded.colorScheme);
-			const save = react.useCallback(async () => {
-				if (draft === null || saving) return;
-				setSaving(true);
+				const replace = () => {
+					const panel = panelRef.current;
+					if (panel === null || anchor === null || anchor === void 0) return;
+					placePanel(anchor, panel);
+				};
+				window.addEventListener("resize", replace);
+				window.addEventListener("scroll", replace, true);
+				return () => {
+					window.removeEventListener("resize", replace);
+					window.removeEventListener("scroll", replace, true);
+				};
+			}, [anchor]);
+			const commit = async (patch) => {
+				setPending((current) => ({ ...current, ...patch }));
 				setSaveFailed(false);
 				try {
-					await configStore.set({ enabled: draft.enabled, colorScheme: draft.colorScheme });
-					// The scope confirms the write and refreshes its snapshot
-					// synchronously before settling; sync the staged form.
-					const confirmed = configStore.getSnapshot();
-					if (confirmed.status === "ready") {
-						setLoaded({ enabled: confirmed.enabled, colorScheme: confirmed.colorScheme });
-						setDraft({ enabled: confirmed.enabled, colorScheme: confirmed.colorScheme });
-					}
+					await store.set(patch);
 				} catch {
 					setSaveFailed(true);
-				} finally {
-					setSaving(false);
 				}
-			}, [draft, saving]);
-			const discard = () => {
-				if (loaded !== null) setDraft(loaded);
-				setSaveFailed(false);
 			};
-			const toggleEnabled = () => {
-				if (draft !== null) setDraft({ ...draft, enabled: !draft.enabled });
+			const chooseScheme = (value) => {
+				if (value !== scheme) commit({ colorScheme: value });
 			};
-			const chooseScheme = (scheme) => {
-				if (draft !== null) setDraft({ ...draft, colorScheme: scheme });
+			const chooseView = (value) => {
+				if (value !== defaultView) commit({ defaultView: value });
 			};
+			const labelOf = (name) => dict(`settings${name[0].toUpperCase()}${name.slice(1)}`);
 			const title = dict("settingsTitle");
-
-			let bodyContent;
-			if (config.status === "unavailable") {
-				bodyContent = react_jsx_runtime.jsxs("p", {
-					className: S.settingsError,
-					children: [
-						dict("settingsLoadFailed"),
-						" ",
-						react_jsx_runtime.jsx("button", {
-							type: "button",
-							className: S.settingsRetry,
-							onClick: () => configStore.reload(),
-							children: dict("settingsRetry")
-						})
-					]
-				});
-			} else if (loaded === null || draft === null) {
-				bodyContent = react_jsx_runtime.jsx("p", {
-					className: S.settingsLoading,
-					children: dict("loading")
-				});
-			} else {
-				bodyContent = react_jsx_runtime.jsxs(react_jsx_runtime.Fragment, {
-					children: [
-						react_jsx_runtime.jsx("div", {
-							className: S.settingsField,
-							children: react_jsx_runtime.jsxs("div", {
-								className: S.settingsSwitchRow,
+			const panel = react_jsx_runtime.jsxs("div", {
+				ref: panelRef,
+				className: S.settingsPanel,
+				role: "dialog",
+				"aria-label": title,
+				// Nothing may paint at the viewport origin before placement runs.
+				style: { visibility: "hidden" },
+				children: [
+					react_jsx_runtime.jsxs("div", {
+						className: S.panelHead,
+						children: [
+							react_jsx_runtime.jsxs("span", {
+								className: S.panelTitleLabel,
 								children: [
-									react_jsx_runtime.jsx("button", {
-										type: "button",
-										role: "switch",
-										"aria-checked": draft.enabled,
-										"aria-label": dict("settingsEnabled"),
-										disabled: saving,
-										className: draft.enabled ? `${S.settingsSwitch} ${S.settingsSwitchOn}` : S.settingsSwitch,
-										onClick: toggleEnabled,
-										children: react_jsx_runtime.jsx("span", { className: S.settingsThumb })
+									react_jsx_runtime.jsxs("svg", {
+										width: 14,
+										height: 14,
+										viewBox: "0 0 24 24",
+										fill: "none",
+										stroke: "currentColor",
+										"stroke-width": 2,
+										"stroke-linecap": "round",
+										"stroke-linejoin": "round",
+										"aria-hidden": "true",
+										children: [
+											react_jsx_runtime.jsx("circle", { cx: 12, cy: 12, r: 9 }),
+											react_jsx_runtime.jsx("path", { d: "M12 11v5" }),
+											react_jsx_runtime.jsx("path", { d: "M12 8h.01" })
+										]
 									}),
-									react_jsx_runtime.jsx("span", { className: S.settingsFieldLabel, children: dict("settingsEnabled") })
+									react_jsx_runtime.jsx("span", { children: title })
 								]
 							})
-						}),
-						react_jsx_runtime.jsx("p", {
-							className: S.settingsFieldHint,
-							children: dict("settingsEnabledHint")
-						}),
-						react_jsx_runtime.jsxs("div", {
-							className: S.settingsField,
-							children: [
-								react_jsx_runtime.jsx("span", { className: S.settingsFieldLabel, children: dict("settingsScheme") }),
-								react_jsx_runtime.jsx("div", {
-									className: S.settingsSwatches,
-									children: Object.keys(COLOR_SCHEMES).map((scheme) => react_jsx_runtime.jsx("button", {
-										type: "button",
-										disabled: saving,
-										className: S.settingsSwatch,
-										"data-active": draft.colorScheme === scheme,
-										onClick: () => chooseScheme(scheme),
-										children: [
-											react_jsx_runtime.jsx("span", {
-												className: S.settingsSwatchCells,
-												children: COLOR_SCHEMES[scheme].slice(1).map((color, index) => react_jsx_runtime.jsx("span", {
-													className: S.settingsSwatchCell,
-													style: { background: color }
-												}, `cell-${index}`))
-											}),
-											react_jsx_runtime.jsx("span", {
-												className: S.settingsSwatchLabel,
-												children: dict(`settings${scheme[0].toUpperCase()}${scheme.slice(1)}`)
-											})
-										]
-									}, scheme))
-								})
-							]
-						}),
-						react_jsx_runtime.jsx("p", {
-							className: S.settingsFieldHint,
-							children: dict("settingsSchemeHint")
-						}),
-						react_jsx_runtime.jsxs("div", {
-							className: S.settingsFooter,
-							children: [
-								saveFailed ? react_jsx_runtime.jsx("p", {
-									className: S.settingsFooterError,
-									children: dict("settingsSaveFailed")
-								}) : null,
-								react_jsx_runtime.jsx("button", {
+						]
+					}),
+					react_jsx_runtime.jsx("div", { className: S.panelRule, "aria-hidden": "true" }),
+					react_jsx_runtime.jsxs("div", {
+						className: S.settingsGroup,
+						children: [
+							react_jsx_runtime.jsx("span", { className: S.settingsGroupLabel, children: dict("settingsScheme") }),
+							react_jsx_runtime.jsx("div", {
+								className: S.settingsSwatches,
+								children: schemes.map((name) => react_jsx_runtime.jsxs("button", {
 									type: "button",
-									className: `${S.settingsBtn} ${S.settingsDiscard}`,
-									disabled: !dirty || saving,
-									onClick: discard,
-									children: dict("settingsDiscard")
-								}),
-								react_jsx_runtime.jsx("button", {
+									className: S.settingsSwatch,
+									"data-active": scheme === name,
+									"aria-pressed": scheme === name,
+									title: labelOf(name),
+									onClick: () => chooseScheme(name),
+									children: [
+										react_jsx_runtime.jsx("span", {
+											className: S.settingsSwatchCells,
+											children: COLOR_SCHEMES[name].slice(1).map((color, index) => react_jsx_runtime.jsx("span", {
+												className: S.settingsSwatchCell,
+												style: { background: color }
+											}, `cell-${index}`))
+										}),
+										react_jsx_runtime.jsx("span", {
+											className: S.settingsSwatchLabel,
+											children: labelOf(name)
+										})
+									]
+								}, name))
+							})
+						]
+					}),
+					react_jsx_runtime.jsxs("div", {
+						className: S.settingsGroup,
+						children: [
+							react_jsx_runtime.jsx("span", { className: S.settingsGroupLabel, children: dict("settingsDefaultView") }),
+							react_jsx_runtime.jsx("div", {
+								className: S.seg,
+								role: "group",
+								"aria-label": dict("settingsDefaultView"),
+								children: VIEW_MODES.map((mode) => react_jsx_runtime.jsx("button", {
 									type: "button",
-									className: `${S.settingsBtn} ${S.settingsSave}`,
-									disabled: !dirty || saving,
-									onClick: save,
-									children: dict(saving ? "settingsSaving" : "settingsSave")
-								})
-							]
-						})
-					]
-				});
-			}
-
-			return react_jsx_runtime.jsxs("li", {
-				className: open ? `${S.settingsCard} ${S.settingsCardOpen}` : S.settingsCard,
-				children: [
-					react_jsx_runtime.jsxs("button", {
-						type: "button",
-						className: S.settingsHeader,
-						"aria-expanded": open,
-						"aria-label": `${dict(open ? "settingsCollapse" : "settingsExpand")}: ${title}`,
-						onClick: () => setOpen(!open),
+									className: S.segBtn,
+									"data-active": defaultView === mode,
+									"aria-pressed": defaultView === mode,
+									onClick: () => chooseView(mode),
+									children: dict(mode === "month" ? "viewMonth" : "viewYear")
+								}, mode))
+							})
+						]
+					}),
+					react_jsx_runtime.jsxs("div", {
+						className: S.panelFoot,
 						children: [
-							react_jsx_runtime.jsxs("span", {
-								className: S.settingsHeadText,
+							react_jsx_runtime.jsxs("div", {
+								className: S.footLegend,
 								children: [
-									react_jsx_runtime.jsx("span", { className: S.settingsName, children: title }),
-									react_jsx_runtime.jsx("span", { className: S.settingsDesc, children: dict("settingsDescription") })
+									dict("less"),
+									...palette.map((color, level) => react_jsx_runtime.jsx("span", {
+										className: S.legendCell,
+										style: { background: color },
+										title: legend[level] ?? ""
+									}, `foot-${level}`)),
+									dict("more")
 								]
 							}),
-							dirty ? react_jsx_runtime.jsx("span", {
-								className: S.settingsPending,
-								children: dict("settingsUnsaved")
-							}) : null,
-							react_jsx_runtime.jsx("svg", {
-								width: 14,
-								height: 14,
-								className: open ? `${S.settingsChevron} ${S.settingsChevronOpen}` : S.settingsChevron,
-								viewBox: "0 0 14 14",
-								fill: "none",
-								xmlns: "http://www.w3.org/2000/svg",
-								children: react_jsx_runtime.jsx("path", {
-									d: "M11.8486 5.5L11.4238 5.92383L8.69727 8.65137C8.44157 8.90706 8.21562 9.13382 8.01172 9.29785C7.79912 9.46883 7.55595 9.61756 7.25 9.66602C7.08435 9.69222 6.91565 9.69222 6.75 9.66602C6.44405 9.61756 6.20088 9.46883 5.98828 9.29785C5.78438 9.13382 5.55843 8.90706 5.30273 8.65137L2.57617 5.92383L2.15137 5.5L3 4.65137L3.42383 5.07617L6.15137 7.80273C6.42595 8.07732 6.59876 8.24849 6.74023 8.3623C6.87291 8.46904 6.92272 8.47813 6.9375 8.48047C6.97895 8.48703 7.02105 8.48703 7.0625 8.48047C7.07728 8.47813 7.12709 8.46904 7.25977 8.3623C7.40124 8.24849 7.57405 8.07732 7.84863 7.80273L10.5762 5.07617L11 4.65137L11.8486 5.5Z",
-									fill: "currentColor"
-								})
+							saveFailed ? react_jsx_runtime.jsx("div", {
+								className: S.footError,
+								children: dict("settingsSaveFailed")
+							}) : react_jsx_runtime.jsx("div", {
+								className: S.footRule,
+								children: dict("settingsThresholdNote")
 							})
 						]
-					}),
-					open ? react_jsx_runtime.jsx("div", {
-						className: S.settingsBody,
-						children: bodyContent
-					}) : null
+					})
 				]
 			});
+			return reactDom.createPortal(panel, document.body);
 		}
 		//#endregion
 
 		//#region plugin body
 		/**
-		 * Settings namespace this plugin's card edits — must match the
-		 * namespace the Host registers (lib/index.js). Spelled here rather
-		 * than imported: a client package must not depend on a Host package.
+		 * Settings namespace the card reads/writes — must match the namespace
+		 * the Host registers (lib/index.js). Spelled here rather than imported:
+		 * a client package must not depend on a Host package.
 		 */
 		const SETTINGS_NS = "token-heatmap";
 		/** Services required by the client plugin body. */
 		const inject = ["slots", "locale", "connection", "remote", "settingsScope"];
 
 		/**
-		 * Client plugin body: register the dictionaries, the input-dock entry
-		 * (heatmap below the composer card on the new-session screen) and the
-		 * plugin settings card (设置 → 插件 → 插件配置), all backed by the
-		 * `token-heatmap` settings namespace through a bound settings scope.
+		 * Client plugin body: register the dictionaries and the input-dock entry
+		 * (the heatmap below the composer card on the new-session screen), backed
+		 * by the `token-heatmap` settings namespace through a bound settings
+		 * scope. The card configures itself through its own ⚙ panel, so this
+		 * plugin does NOT register into `settings.plugin.item` (the official
+		 * 设置 → 插件 → 插件配置 card seat) any more — the Host still serves the
+		 * namespace, it just has no configuration card to dispatch.
 		 *
 		 * Slot-kind contract: `conversation.input.dock` is a LIST slot, so its
-		 * registration is keyed by `id`; `settings.plugin.item` is a KEYED slot,
-		 * so its registration must carry `key` (the settings namespace the card
-		 * edits) — registering with `id` instead throws
-		 * `keyed slot "settings.plugin.item" requires options.key` and fails
-		 * the whole plugin load. The card is only dispatched by the official
-		 * 插件配置 tab when the Host actually SERVES that namespace, which is
-		 * why this plugin registers it on the Host side too.
+		 * registration is keyed by `id` (a `settings.plugin.item` registration
+		 * would instead need `key`, the settings namespace the card edits).
 		 * @param ctx - client root context.
 		 */
 		function apply(ctx) {
@@ -977,21 +1230,19 @@ window.__ModuleLoader__.load({
 				order: 10,
 				locale: NS
 			}, TokenHeatmap));
-			ctx.slots.inject("settings.plugin.item", () => ctx.slots.register({
-				name: "settings.plugin.item",
-				key: SETTINGS_NS,
-				order: 30,
-				locale: NS
-			}, TokenHeatmapSettingsCard));
 		}
 		//#endregion
 
 		exports.apply = apply;
 		exports.inject = inject;
 		exports.TokenHeatmap = TokenHeatmap;
-		exports.TokenHeatmapSettingsCard = TokenHeatmapSettingsCard;
+		exports.TokenHeatmapInlineSettings = TokenHeatmapInlineSettings;
 		exports.buildGrid = buildGrid;
+		exports.buildMonthGrid = buildMonthGrid;
 		exports.levelOf = levelOf;
+		exports.monthLabelFull = monthLabelFull;
+		exports.dateLabel = dateLabel;
+		exports.shiftMonthKey = shiftMonthKey;
 		exports.CELL_COLORS = CELL_COLORS;
 		exports.COLOR_SCHEMES = COLOR_SCHEMES;
 		exports.createConfigStore = createConfigStore;