@starwish-ai/xingyuan-dsh 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -5,6 +5,193 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.4] - 2026-08-28
+
+> **Note:** trailing chart statistics no longer count future pre-checked days (see
+> *Changed*). Chart cards generated by this version carry a "generated on" stamp so a
+> stale card is distinguishable from current data; cards written by earlier versions
+> replay unchanged, without the stamp.
+
+**Charts and records now tell the truth about time.** Future pre-checked days were
+counted by every trailing statistic as if they had already happened — a "how is this
+week going" chart could be inflated by check-ins for days that have not occurred, and a
+task's check-in grid could end up showing nothing but future days while today's check-in
+was invisible. Undoing a check-in said "revert today's?" while actually reverting a
+future pre-check, because the pages let the server fall back to "most recent record".
+
+### Added
+- **Chart snapshot stamp**: chart events carry `generatedAt` and the card renders a
+  localized "generated on" date; cards generated by older versions replay without it
+  (the field is optional and degrades honestly).
+- **"No schedule" ≠ 0%**: in the daily completion-rate trend, days with no scheduled
+  opportunity render as an empty slot labelled "no schedule" (tooltip and screen reader
+  alike) instead of a 0% data point.
+- The completion-rate chart annotates its subtitle with "including unclaimed tasks"
+  when pending tasks count toward the total, so the denominator is never a mystery.
+- **Startup consistency sweep** (`src/consistency-sweep.ts`): check-ins whose task no
+  longer exists, tasks whose wish was deleted out from under them, and dangling
+  micro-action states are cleaned once per launch through the same cascade the delete
+  tools use. Idempotent, runs after activation without blocking it, and pinned by
+  `test/integrity.test.ts`.
+- **Task-detail grid window**: the check-in grid shows the last 28 opportunity days up
+  to today, plus every checked day — future pre-checks stay visible (they are standing
+  commitments), and check-ins outside the opportunity series (deadline-free tasks) make
+  the grid their check-in history. Today is never squeezed out of the window, however
+  many future days are pre-checked; unchecked future days remain in the "upcoming"
+  preview line.
+- **gzip content negotiation** for the standalone pages (`/xingyuan/today`, `/calendar`,
+  `/growth`) per RFC 9110 §12.5.3: absent header accepts any coding, an empty value or
+  an explicit opt-out gets plaintext, `Vary: Accept-Encoding` is always sent, and the
+  compressed template is cached per body.
+- **Request timeout**: client fetches abort after 15 s with a localized message instead
+  of hanging forever.
+- **Focus refetch**: page data refetches when the window regains focus if older than
+  60 s, and always when the local day has changed — overnight sessions no longer show
+  yesterday's "today".
+- **Undo readability**: the detail panel's undo button announces the exact day it will
+  revert (screen-reader label), and its visibility no longer requires today to be the
+  checked day — a pre-check can be undone right where it was made.
+
+### Fixed
+- **The cancel dialog said "today" while a different day was reverted.** The today page
+  and the task detail panel posted the cancel without a date and the server falls back
+  to the most recent check-in — which a future pre-check satisfies. Every page now sends
+  the explicit date; the dialog, the toast and the reverted record all name the same day.
+- `weekComparison` folded future pre-checks into weekday buckets as if they were in the
+  current week; the week window is now a closed interval from last Monday to today.
+- Wish progress **rounded** instead of flooring: 249/250 displayed as 100% and could
+  archive the wish one day early.
+- Checking in an expired (closed) task failed with a generic error; it now explains that
+  the deadline must be extended to revive the task before further check-ins.
+- Concurrent writes to the global document (coach style, profile, category colors,
+  micro-action state) could lose updates under interleaving; all writers now serialize
+  through one promise chain, a failed writer no longer poisons the chain, and no-op
+  mutations skip the write entirely.
+- The memory page could deadlock with a perpetual "loading more" spinner when an
+  in-flight request was superseded by a newer one (the reset ran on only one of two
+  completion paths).
+- The calendar's post-action detail refetch swallowed failures; the panel now shows an
+  error state with a retry button instead of silently keeping stale content.
+- A deadline-free one-shot task disappeared from the today page the moment it was
+  checked; the completed row now stays revocable for the rest of the day (it never
+  reappears the next day).
+- `/xingyuan/api/day` and `/xingyuan/api/range` answered a malformed `date` with an
+  empty day list or an unlabelled `RangeError`; both now reject with a structured
+  `bad_date` error, consistent with the POST action surface.
+- Creating a task with a name over 100 characters through a page action failed with a
+  bare validation message; the error now states the limit and the actual length.
+- The claim button in the calendar is gated to the picked day being today, matching the
+  server-side anchor semantics.
+- Display dates across cards, toasts and pages are localized (ISO strings remain only in
+  confirm-dialog copy and screen-reader strings, per the documented convention).
+- The standalone growth page used `color-mix()`, which some shells render as an invalid
+  declaration; the darker tone is now precomputed in JS.
+
+### Changed
+- Trailing chart statistics (trend, daily rate, week comparison, by-category, ranking,
+  time-of-day, weekday activity) only count check-ins up to today; the calendar heatmap
+  deliberately keeps future pre-checks visible. Chart cards are snapshots of their
+  generation time — the coach guide tells the model to regenerate for current data.
+- `cancel_check_in_task` parameter guidance now instructs the model to pass the date
+  whenever the user names a day (including "today"), so the "most recent" fallback is a
+  deliberate choice rather than an accident.
+- zh copy no longer pads localized dates with spaces ("已撤销 8月29日 的打卡" →
+  "已撤销8月29日的打卡"), and the grid legend says "待打卡" where it previously said
+  "未来机会日" for what is now only ever today's pending slot.
+
+## [0.5.3] - 2026-08-28
+
+> **Note:** this is a patch release but it carries one breaking change — the `xingyuan`
+> settings namespace is replaced by `xingyuan-pref` (see *Removed*). Consumers of the
+> `./domain` subpath must also adapt to `makeXingyuanStore()` taking a second, required
+> argument. Read *Upgrading from 0.5.2 or earlier* before updating.
+
+**Chat preferences are now always editable.** Settings → XingYuan rendered the
+write-confirmation toggle and the memory-injection limit as permanently disabled until a
+XingYuan session had been opened once since the last dsh start; clicking them did nothing
+and produced no error. Both preferences lived in the preset-layer namespace, which only
+comes into existence when the preset is first mounted, so they now live in a
+bundle-resident namespace registered whenever the bundle row is active.
+
+### Upgrading from 0.5.2 or earlier
+
+The two chat preferences moved from the `xingyuan` block of `$DSH_HOME/settings.yaml` to a
+new `xingyuan-pref` block. **A value you had customised is not carried over** and falls back
+to the default: `confirmWrites` returns to `true` (the safe direction — write actions ask for
+confirmation again) and `memoryInjectLimit` to `40`. Re-apply your choices under
+**Settings → XingYuan → Chat preferences**. The leftover `xingyuan:` block is inert and is
+safe to delete.
+
+### Added
+- **`xingyuan-pref` settings namespace** (`src/pref-settings.ts`), installed by the bundle
+  layer next to the existing `xingyuan-ui` namespace, carrying `confirmWrites` (default
+  `true`) and `memoryInjectLimit` (default `40`, integer `5`–`200`). The schema declares
+  `.step(1)`, so the Host also rejects fractional values that a hand-edited settings
+  document or a direct RPC write could otherwise smuggle in.
+- **Shared preference policy module** (`src/pref-policy.ts`) holding the bounds, defaults
+  and input parser for both halves — the host module depends on
+  `@deepseek-ai/dsh-settings` and must never reach the browser bundle. This also removes
+  the `5`/`200`/`40` literals that were previously repeated in the settings page. Covered
+  by `test/pref-policy.test.ts`.
+- **Write verification**: `scope.set()` resolves rather than rejects on failure (the client
+  controller catches, recovers and returns silently), so `toastError` never fired. The page
+  now compares the snapshot after each write and raises a "did not save" toast when the
+  value did not change. Both controls share one scope — and therefore one write queue — so
+  the comparison is gated on a per-component write sequence number to stay honest under
+  interleaved writes (see below).
+- **Regression lock** (`test/pref-settings.test.ts`): five tests pinning that the bundle
+  layer registers `xingyuan-pref` as soon as the settings service is available, that the
+  read thunk resolves fresh on every call, that the headless path falls back to the schema
+  defaults, and — structurally — that **no namespace bound by the settings page is ever
+  registered from the preset layer**. That last one is the abstract shape of this bug and is
+  what stops it from coming back.
+- **Four-way readiness notice** for the preferences card: loading, remote/temporary
+  connection (`mode === 'memory'`), namespace not registered, and read-only document. The
+  previous code only covered the first two, leaving the rest as silently disabled controls.
+
+### Fixed
+- The two preferences could not be changed before the first XingYuan session of the process
+  — the root cause described above.
+- The write-confirmation toggle rendered as **on** whenever its value was unavailable
+  (`value?.confirmWrites !== false` reads "unknown" as "true"), which is the worst possible
+  default for a safety switch. It now falls back to the schema default explicitly.
+- Namespace-unavailable and read-only states disabled the controls with no explanation.
+- The "did not save" toast could fire on a write that **had** been saved. Both controls share
+  one settings scope, and the client controller fences writes with a generation counter: when
+  a write is superseded by a newer one it only records a pending revision and does **not**
+  fold the result into the snapshot, while the superseded write's `.then` still runs first and
+  sees the stale value. Verification is now skipped for superseded writes, and the number
+  input got the pending guard the toggle already had.
+- Clearing the memory-injection-limit field and blurring reported "enter an integer between 5
+  and 200" while simultaneously refilling the field with the saved value — two contradictory
+  messages at once. An empty field is again treated as abandoning the edit.
+- Tool descriptions for the creation / check-in / cancel-check-in tools asserted that a system
+  confirmation card would appear. Toggle **Confirm write actions** off and the model kept
+  telling users a card had been shown when none was. Tool descriptions are baked in at
+  registration and dsh-tools requires a plain string (no getter), so they are now worded to
+  hold in both states instead of asserting the card. Delete tools are unaffected — deletes
+  always confirm.
+
+### Changed
+- The preset layer no longer registers a settings namespace. It reads preferences through
+  `ctx.xingyuan.prefs()` — a thunk that resolves the current value on every call, so edits
+  still take effect immediately without re-registering tools or prompts. The remaining
+  `Config` fields (`batchWishLimit`, `chartTrendDays`, …) have no settings UI and stay as
+  composition-only entry config, which matches the upstream rule that a namespace should
+  carry only the user-editable subset.
+- **Breaking for `./domain` consumers**: `makeXingyuanStore(domain)` now takes a second,
+  required argument — `makeXingyuanStore(domain, readPrefs)`, where `readPrefs` is a thunk
+  returning the resolved chat preferences. The required-ness is deliberate: every call site
+  (one in production, five in tests) is surfaced by the compiler rather than silently
+  missing the wiring. `XingyuanStore` gained a matching `prefs()` method.
+
+### Removed
+- The preset-layer `xingyuan` settings namespace and the `confirmWrites` /
+  `memoryInjectLimit` fields of the preset `Config`. **A value customised under the old
+  `xingyuan:` section of `$DSH_HOME/settings.yaml` is no longer read and falls back to the
+  default** — `confirmWrites` therefore returns to `true`, the conservative direction. The
+  stale section is left in the document and is harmless.
+
 ## [0.5.2] - 2026-08-27
 
 ### Added

package/lib/client/api.js

@@ -40,8 +40,27 @@ export function describeError(e) {
 export async function postAction(path, body) {
     return postJson(`/xingyuan/api/action/${path}`, body);
 }
+/** 请求超时：手动 AbortController——AbortSignal.timeout 为 Baseline 2024 "Newly available"，
+ * 不满足 dsh 壳的保守浏览器矩阵（同 color-mix 禁令的判断口径），不用。 */
+const REQUEST_TIMEOUT_MS = 15_000;
+async function fetchWithTimeout(path, init) {
+    const controller = new AbortController();
+    const timer = window.setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        return await fetch(path, { ...init, signal: controller.signal });
+    }
+    catch (e) {
+        // 超时中止统一转本地化文案；真实网络错误原样抛出（保留连接拒绝等语义）
+        if (e instanceof DOMException && e.name === 'AbortError')
+            throw new Error(t('common.requestTimeout'));
+        throw e;
+    }
+    finally {
+        window.clearTimeout(timer);
+    }
+}
 export async function postJson(path, body) {
-    const response = await fetch(path, {
+    const response = await fetchWithTimeout(path, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify(body),
@@ -49,7 +68,7 @@ export async function postJson(path, body) {
     return parsePayload(response, () => t('common.actionFailed'));
 }
 export async function getJson(path) {
-    const response = await fetch(path, { headers: { accept: 'application/json' } });
+    const response = await fetchWithTimeout(path, { headers: { accept: 'application/json' } });
     return parsePayload(response, () => t('common.requestFailed'));
 }
 async function parsePayload(response, fallback) {

package/lib/client/cards.js

@@ -11,7 +11,7 @@ import { toast, toastError } from './ui.js';
 import { localYmd, softConfirm } from './hooks.js';
 import { useXyT, t, activeLocale } from './i18n.js';
 import { categoryVars } from '../category-color.js';
-import { cycleLabel, durationText, dateSuffix } from './pages/format.js';
+import { cycleLabel, durationText, dateSuffix, formatMediumDate, formatShortDate } from './pages/format.js';
 function WishView(props) {
     const t = useXyT();
     const wish = props.node.data.data;
@@ -95,7 +95,7 @@ function TaskView(props) {
     const showClaim = !deleted && phase === 'idle' && task.status === 'pending';
     const showCheckIn = !deleted && phase !== 'done' && (task.status === 'in_progress' || phase === 'claimed');
     const preview = event.opportunityPreview.length > 0
-        ? t('task.upcoming', { dates: event.opportunityPreview.join(activeLocale() === 'en' ? ', ' : '、') })
+        ? t('task.upcoming', { dates: event.opportunityPreview.map((date) => formatShortDate(date)).join(activeLocale() === 'en' ? ', ' : '、') })
         : undefined;
     return createElement('div', { className: `xy-card ${deleted ? 'xy-deleted' : ''}` }, createElement('div', { className: 'xy-card-head' }, createElement('span', { className: 'xy-badge xy-badge-task' }, t('badge.task')), createElement('span', { className: 'xy-title' }, deleted ? t('state.deleted', { title: task.name }) : task.name), !deleted && phase === 'done'
         ? createElement('span', { className: 'xy-meta xy-actioned' }, 
@@ -105,7 +105,7 @@ function TaskView(props) {
         ? createElement('button', { className: 'xy-btn xy-btn-inline', disabled: busy, onClick: () => run('claim') }, t('action.claim'))
         : null, showCheckIn
         ? createElement('button', { className: 'xy-btn xy-btn-primary xy-btn-inline', disabled: busy, onClick: () => run('checkin') }, t('action.checkin'))
-        : null), createElement('div', { className: 'xy-meta' }, `${cycleLabel(task.checkInCycle)}${task.dueDate !== undefined ? ` · ${t('task.due', { date: task.dueDate })}` : ''} · ${durationText(task.completedDays, task.requiredDays)}`), deleted === false && preview !== undefined
+        : null), createElement('div', { className: 'xy-meta' }, `${cycleLabel(task.checkInCycle)}${task.dueDate !== undefined ? ` · ${t('task.due', { date: formatShortDate(task.dueDate) })}` : ''} · ${durationText(task.completedDays, task.requiredDays)}`), deleted === false && preview !== undefined
         ? createElement('div', { className: 'xy-preview' }, preview)
         : null);
 }
@@ -139,23 +139,29 @@ function CheckinView(props) {
     const event = props.node.data.data;
     const cancelled = event.op === 'cancelled';
     return createElement('div', { className: 'xy-card xy-checkin' }, createElement('div', { className: 'xy-card-head' }, createElement('span', { className: `xy-glyph ${cancelled ? 'xy-glyph-back' : 'xy-glyph-ok'}`, 'aria-hidden': 'true' }, cancelled ? '↩' : '✓'), createElement('span', { className: 'xy-title' }, cancelled
-        ? t('checkin.cancelled', { task: event.taskName, date: event.date })
-        : t('checkin.success', { task: event.taskName }))), createElement('div', { className: 'xy-meta' }, `${event.date}${event.wishName !== undefined ? ` · ${event.wishName}` : ''} · ${durationText(event.completedDays, event.requiredDays)}`));
+        ? t('checkin.cancelled', { task: event.taskName, date: formatShortDate(event.date) })
+        : t('checkin.success', { task: event.taskName }))), createElement('div', { className: 'xy-meta' }, `${formatShortDate(event.date)}${event.wishName !== undefined ? ` · ${event.wishName}` : ''} · ${durationText(event.completedDays, event.requiredDays)}`));
 }
 function ChartView(props) {
     const t = useXyT();
     const event = props.node.data.data;
     // 悬停柱下标（与成长页悬浮明细同一交互语法；null = 未悬停）
     const [hoverIdx, setHoverIdx] = useState(null);
-    return createElement('div', { className: 'xy-card xy-chart' }, createElement('div', { className: 'xy-card-head' }, createElement('span', { className: 'xy-badge xy-badge-chart' }, t('badge.chart')), createElement('span', { className: 'xy-title' }, event.title), event.subtitle !== undefined ? createElement('span', { className: 'xy-meta' }, event.subtitle) : null), chartBody(event, t('chart.noData'), hoverIdx, setHoverIdx));
+    return createElement('div', { className: 'xy-card xy-chart' }, createElement('div', { className: 'xy-card-head' }, createElement('span', { className: 'xy-badge xy-badge-chart' }, t('badge.chart')), createElement('span', { className: 'xy-title' }, event.title), event.subtitle !== undefined ? createElement('span', { className: 'xy-meta' }, event.subtitle) : null), 
+    // 快照时点标注（事件溯源：卡片=当时的事实）：无 generatedAt 的旧事件诚实降级不显示。
+    // 中格式带年份——回放的旧卡可能跨年，「生成于 3月5日」须能定位到哪一年。
+    // ISO → 本地日再格式化：直接 slice 会把 UTC 日期当本地日（UTC+8 零点后 8 小时内差一天）
+    event.generatedAt !== undefined
+        ? createElement('div', { className: 'xy-meta' }, t('chart.generatedAt', { date: formatMediumDate(localYmd(new Date(event.generatedAt))) }))
+        : null, chartBody(event, t('chart.noData'), t('chart.noSchedule'), hoverIdx, setHoverIdx));
 }
 /** 图表卡主体：四类渲染路径（占比条/占比列表/热力格/柱图）颜色全部走主题变量，深浅色自适应。 */
-function chartBody(event, noDataText, hoverIdx, onHover) {
+function chartBody(event, noDataText, noScheduleText, hoverIdx, onHover) {
     const { chartType, data } = event;
     if (data.length === 0)
         return createElement('div', { className: 'xy-meta' }, noDataText);
-    const max = Math.max(...data.map((d) => d.value), 1);
-    const labelValue = (d) => `${d.label}${activeLocale() === 'en' ? ': ' : '：'}${d.value}`;
+    const max = Math.max(...data.filter((d) => !d.inactive).map((d) => d.value), 1);
+    const labelValue = (d) => `${d.label}${activeLocale() === 'en' ? ': ' : '：'}${d.inactive === true ? noScheduleText : d.value}`;
     if (chartType === 'arcbars') {
         const ratio = Math.min(Math.max(data[0].ratio ?? 0, 0), 1);
         return createElement('div', { className: 'xy-arcwrap' }, createElement('div', { className: 'xy-arcnum' }, `${Math.round(ratio * 100)}%`), 
@@ -187,19 +193,22 @@ function chartBody(event, noDataText, hoverIdx, onHover) {
         const r = Math.min(2, h, w / 2);
         return `M${x},${y + h}L${x},${y + r}Q${x},${y} ${x + r},${y}L${x + w - r},${y}Q${x + w},${y} ${x + w},${y + r}L${x + w},${y + h}Z`;
     };
-    const bars = data.map((d, i) => {
+    const bars = data.flatMap((d, i) => {
+        // 无安排日不画柱（缺失≠0）：空槽由下标占位保留，柱序与日期轴不塌缩
+        if (d.inactive === true)
+            return [];
         // 微值可见性下限：有值但按比例不足 2px 的柱给 2px，避免「有数据却看不见」
         const rawH = Math.round((d.value / max) * (height - 24));
         const h = d.value > 0 ? Math.max(rawH, 2) : rawH;
         const seriesIdx = d.series !== undefined ? seriesList.indexOf(d.series) : -1;
-        return createElement('path', {
-            key: i,
-            d: topRoundedBar(i * step + 2, height - 18 - h, Math.max(step - 4, 2), h),
-            style: { fill: seriesIdx > 0 ? seriesColor(seriesIdx) : 'var(--xyd-accent)', opacity: seriesIdx > 0 ? 0.55 : 0.85 },
-            onMouseEnter: () => onHover(i),
-        }, 
-        // 每根柱子带 <title>：原生悬停提示；精确数值另由上方悬浮明细条实时呈现
-        createElement('title', null, labelValue(d)));
+        return [createElement('path', {
+                key: i,
+                d: topRoundedBar(i * step + 2, height - 18 - h, Math.max(step - 4, 2), h),
+                style: { fill: seriesIdx > 0 ? seriesColor(seriesIdx) : 'var(--xyd-accent)', opacity: seriesIdx > 0 ? 0.55 : 0.85 },
+                onMouseEnter: () => onHover(i),
+            }, 
+            // 每根柱子带 <title>：原生悬停提示；精确数值另由上方悬浮明细条实时呈现
+            createElement('title', null, labelValue(d)))];
     });
     // 标签用原始下标定位：indexOf 会把重复标签（如分组系列的「周一」×2）全部钉到首个位置
     const labelStep = data.length <= 10 ? 1 : Math.ceil(data.length / 8);
@@ -221,7 +230,7 @@ function chartBody(event, noDataText, hoverIdx, onHover) {
     createElement('svg', {
         viewBox: `0 0 ${width} ${height}`, className: 'xy-svg',
         role: 'img', 'aria-label': event.title,
-    }, createElement('line', { x1: 0, y1: height - 18, x2: width, y2: height - 18, style: { stroke: 'var(--dsw-alias-border-l2)' } }), ...bars, ...labels)), createElement('span', { className: 'xy-visually-hidden' }, data.map((d) => `${d.label} ${d.value}`).join(activeLocale() === 'en' ? '; ' : '；')));
+    }, createElement('line', { x1: 0, y1: height - 18, x2: width, y2: height - 18, style: { stroke: 'var(--dsw-alias-border-l2)' } }), ...bars, ...labels)), createElement('span', { className: 'xy-visually-hidden' }, data.map((d) => `${d.label} ${d.inactive === true ? noScheduleText : d.value}`).join(activeLocale() === 'en' ? '; ' : '；')));
 }
 export const CARD_VIEWS = {
     WishView,

package/lib/client/hooks.js

@@ -18,10 +18,18 @@ export function recentRangeDays(days) {
         end: localYmd(now),
     };
 }
+/** 窗口重新可见后的重取门槛（ms）：等价 TanStack Query 的 staleTime——
+ * 数据在此年龄内视为新鲜，聚焦不重取；跨天翻篇则无视门槛一律重取。 */
+const FOCUS_REFETCH_MIN_AGE_MS = 60_000;
 /**
  * 取数三态统一：挂载（或 deps 变化）即拉取，error 存本地化文案，
  * reload 供错误态按钮与动作后刷新复用。path 支持函数形态（如日历按月取参）；
  * 内置序号守卫：快速翻页/连点时慢的旧响应不得覆盖新状态。
+ *
+ * 跨天/回焦自动新鲜化（习惯类应用的基本预期——凌晨挂着的今日页不能还是昨天）：
+ * 监听 visibilitychange/focus，翻篇（本地日期变化）必重取，未翻篇仅当数据年龄
+ * 超过门槛才重取（有节流上限，不空转不定时器）。NN/g「系统应始终让用户知情」：
+ * 时间流逝导致的状态变化要在回到页面时即刻呈现。
  */
 export function usePageData(path, deps = []) {
     const [data, setData] = useState(undefined);
@@ -29,9 +37,13 @@ export function usePageData(path, deps = []) {
     const seqRef = useRef(0);
     const pathRef = useRef(path);
     pathRef.current = path;
+    const lastLoadAtRef = useRef(0);
+    const lastLoadDayRef = useRef(undefined);
     const load = useCallback(() => {
         const seq = ++seqRef.current;
         setError(undefined);
+        lastLoadAtRef.current = Date.now();
+        lastLoadDayRef.current = localYmd(new Date());
         return getJson(typeof pathRef.current === 'function' ? pathRef.current() : pathRef.current)
             .then((payload) => { if (seq === seqRef.current)
             setData(payload); })
@@ -39,6 +51,23 @@ export function usePageData(path, deps = []) {
             setError(describeError(e)); });
     }, deps);
     useEffect(() => { void load(); }, [load]);
+    useEffect(() => {
+        const maybeReload = () => {
+            if (document.visibilityState !== 'visible')
+                return;
+            const today = localYmd(new Date());
+            // 翻篇必取；未翻篇按数据年龄节流（TanStack Query focus 重取的 staleTime 语义）
+            if (lastLoadDayRef.current !== today || Date.now() - lastLoadAtRef.current > FOCUS_REFETCH_MIN_AGE_MS) {
+                void load();
+            }
+        };
+        document.addEventListener('visibilitychange', maybeReload);
+        window.addEventListener('focus', maybeReload);
+        return () => {
+            document.removeEventListener('visibilitychange', maybeReload);
+            window.removeEventListener('focus', maybeReload);
+        };
+    }, [load]);
     return { data, error, reload: load };
 }
 /**

package/lib/client/i18n.js

@@ -41,6 +41,7 @@ const ZH_DICT = {
     'common.edit': '编辑',
     'common.requestFailed': '请求失败',
     'common.actionFailed': '操作失败',
+    'common.requestTimeout': '请求超时，请重试',
     'common.dayUnit': '{n} 天',
     'common.countUnit': '{n} 次',
     'common.countUnitOne': '{n} 次',
@@ -86,18 +87,18 @@ const ZH_DICT = {
     'action.checkinFuture': '提前打卡 {date}',
     'action.checkinThisDay': '打卡此日',
     'action.undoCheckin': '撤销',
-    'action.cancelCheckin': '取消打卡', 'action.expand': '展开详情',
+    'action.cancelCheckin': '取消打卡',
+    'action.cancelCheckinAria': '撤销{date}的打卡', 'action.expand': '展开详情',
     'action.collapse': '收起详情',
     'action.createWish': '＋ 新建愿望',
     'action.createTask': '＋ 新建任务',
     'action.manageCategories': '分类管理',
     'action.askAi': '让 AI 总结',
-    'today.notCheckinDay': '今天不是打卡日',
     // --- 动作反馈 toast ---
     'toast.claimed': '已领取「{name}」，去打卡吧',
     'toast.checkinOk': '打卡成功',
     'toast.undone': '打卡已撤销',
-    'toast.undoneAt': '已撤销 {date} 的打卡',
+    'toast.undoneAt': '已撤销{date}的打卡',
     'toast.wishCreated': '已创建愿望「{title}」',
     'toast.taskCreated': '已创建任务「{name}」',
     'toast.deleted': '已删除「{name}」',
@@ -106,10 +107,10 @@ const ZH_DICT = {
     'toast.categoryColorReset': '「{name}」配色已重置，跟随愿望默认色',
     'toast.categoryDeleted': '已清除「{name}」的自定义颜色',
     // --- 确认弹窗 ---
-    'confirm.futureCheckin': '「{name}」今天不是打卡日，提前打卡 {date} 表示承诺当天完成。确认？',
+    'confirm.futureCheckin': '「{name}」今天不是打卡日，提前打卡{date}表示承诺当天完成。确认？',
     'confirm.undoToday': '确定撤销「{name}」今天的打卡吗？进度将回退。',
-    'confirm.undoAt': '确定撤销「{name}」在 {date} 的打卡吗？进度将回退。',
-    'confirm.futureAt': '「{name}」在 {date} 不是当天，提前打卡表示承诺当天完成。确认？',
+    'confirm.undoAt': '确定撤销「{name}」在{date}的打卡吗？进度将回退。',
+    'confirm.futureAt': '「{name}」{date}不是打卡日，提前打卡表示承诺当天完成。确认？',
     'confirm.deleteTask': '确定删除任务「{name}」吗？其打卡记录将一并删除，不可恢复。',
     'confirm.deleteWish': '确定删除愿望「{name}」吗？下属任务与打卡记录将一并删除，不可恢复。',
     'confirm.renameCategory': '把分类「{old}」下的全部愿望改名为「{new}」吗？（共 {count} 个）', 'confirm.deleteEmptyCategory': '删除空分类「{name}」的自定义颜色吗？',
@@ -230,11 +231,14 @@ const ZH_DICT = {
     'settings.pref.title': '对话偏好',
     'settings.pref.unavailable': '当前连接不支持持久化偏好（远程或临时模式），以下两项不可用。',
     'settings.pref.loading': '偏好加载中…',
+    'settings.pref.notRegistered': '偏好暂不可用（组件未就绪），请稍后重试。',
+    'settings.pref.readOnly': '当前设置文档为只读，无法保存修改。',
     'settings.pref.confirmWrites': '写操作二次确认',
     'settings.pref.confirmWritesHint': '创建愿望/任务、打卡、取消打卡时先弹应用内确认卡（删除始终确认）；关闭后对话中的这类操作将直接执行。',
     'settings.pref.memoryLimit': '记忆注入上限',
     'settings.pref.memoryLimitHint': '每次对话自动注入上下文的记忆条数上限（5-200，默认 40）；失焦后保存。',
     'settings.pref.limitInvalid': '请输入 5-200 的整数',
+    'settings.pref.writeFailed': '保存未生效，请重试。',
     'settings.tabs.title': '标签页显示',
     'settings.tabs.mode.follow': '跟随会话',
     'settings.tabs.mode.show': '始终显示',
@@ -254,18 +258,20 @@ const ZH_DICT = {
     'micro.progress': '进度 {done}/{total} 完成',
     // --- 打卡卡 ---
     'checkin.success': '「{task}」打卡成功',
-    'checkin.cancelled': '已取消「{task}」{date} 的打卡',
+    'checkin.cancelled': '已取消「{task}」{date}的打卡',
     // --- 图表卡 ---
     'chart.noData': '暂无数据',
+    'chart.noSchedule': '无安排',
+    'chart.generatedAt': '生成于 {date}',
     // --- 详情聚合视图 ---
     'detail.grid.title': '打卡记录',
-    'detail.grid.summary': '近 {total} 个机会日：已打 {checked}，未打 {missed}，未来 {future}',
+    'detail.grid.summary': '近 {total} 格：已打 {checked}，未打 {missed}，待打卡 {future}',
     'detail.legend.checked': '已打卡',
     'detail.legend.missed': '未打卡',
-    'detail.legend.future': '未来机会日',
+    'detail.legend.future': '待打卡',
     'detail.grid.checked': '{date} 已打卡',
     'detail.grid.missed': '{date} 未打卡',
-    'detail.grid.future': '{date} 未来机会日',
+    'detail.grid.future': '{date} 待打卡',
     'detail.next.title': '接下来的机会日：{dates}',
     'detail.micro.title': '微行动进度',
     'detail.micro.idle': '尚未开始微行动拆解（可在对话里说「帮我拆解」）。',
@@ -356,6 +362,7 @@ const EN_DICT = {
     'common.edit': 'Edit',
     'common.requestFailed': 'Request failed',
     'common.actionFailed': 'Action failed',
+    'common.requestTimeout': 'Request timed out, please retry',
     'common.dayUnit': '{n} days',
     'common.countUnit': '{n} times',
     'common.countUnitOne': '{n} time',
@@ -398,13 +405,13 @@ const EN_DICT = {
     'action.checkinThisDay': 'Check in',
     'action.undoCheckin': 'Undo',
     'action.cancelCheckin': 'Undo check-in',
+    'action.cancelCheckinAria': 'Undo the check-in on {date}',
     'action.expand': 'Details',
     'action.collapse': 'Hide',
     'action.createWish': '+ New wish',
     'action.createTask': '+ New task',
     'action.manageCategories': 'Categories',
     'action.askAi': 'AI summary',
-    'today.notCheckinDay': 'Not a check-in day today',
     'toast.claimed': 'Claimed “{name}”. Time to check in!',
     'toast.checkinOk': 'Checked in',
     'toast.undone': 'Check-in reverted',
@@ -536,11 +543,14 @@ const EN_DICT = {
     'settings.pref.title': 'Chat preferences',
     'settings.pref.unavailable': 'This connection cannot persist preferences (remote or temporary mode); the two options below are disabled.',
     'settings.pref.loading': 'Loading preferences…',
+    'settings.pref.notRegistered': 'Preferences are unavailable right now (component not ready); please retry later.',
+    'settings.pref.readOnly': 'The settings document is read-only; changes cannot be saved.',
     'settings.pref.confirmWrites': 'Confirm write actions',
     'settings.pref.confirmWritesHint': 'Show an in-app confirmation before creating wishes/tasks, checking in or canceling (deletes always confirm). Turn off to execute directly.',
     'settings.pref.memoryLimit': 'Memory injection limit',
     'settings.pref.memoryLimitHint': 'Max memories auto-injected per chat (5-200, default 40); saved on blur.',
     'settings.pref.limitInvalid': 'Enter an integer between 5 and 200',
+    'settings.pref.writeFailed': 'The change did not save; please try again.',
     'settings.tabs.title': 'Tab visibility',
     'settings.tabs.mode.follow': 'Follow session',
     'settings.tabs.mode.show': 'Always show',
@@ -560,14 +570,16 @@ const EN_DICT = {
     'checkin.success': '“{task}” checked in',
     'checkin.cancelled': 'Cancelled the check-in of “{task}” on {date}',
     'chart.noData': 'No data yet',
+    'chart.noSchedule': 'Not scheduled',
+    'chart.generatedAt': 'Generated on {date}',
     'detail.grid.title': 'Check-in record',
-    'detail.grid.summary': 'Last {total} opportunity days: {checked} checked, {missed} missed, {future} upcoming',
+    'detail.grid.summary': 'Last {total} cells: {checked} checked, {missed} missed, {future} pending',
     'detail.legend.checked': 'Checked in',
     'detail.legend.missed': 'Missed',
-    'detail.legend.future': 'Upcoming',
+    'detail.legend.future': 'Pending today',
     'detail.grid.checked': '{date} checked in',
     'detail.grid.missed': '{date} missed',
-    'detail.grid.future': '{date} upcoming opportunity',
+    'detail.grid.future': '{date} pending check-in',
     'detail.next.title': 'Upcoming opportunity dates: {dates}',
     'detail.micro.title': 'Micro-step progress',
     'detail.micro.idle': 'No micro-step plan yet (ask “help me break it down” in chat).',

package/lib/client/index.js

@@ -79,10 +79,12 @@ export function apply(ctx) {
     // label 用 thunk 跟随当前语言；locale 声明让壳在语言切换时刷新标签行。
     ctx.slots.inject('conversation.view', () => installTabVisibility(ctx));
     // 星愿设置整页（设置 → 星愿）：教练风格/画像（星愿库）+ 二次确认开关与注入上限
-    // （preset 命名空间）+ 标签页显隐（bundle 常驻命名空间 xingyuan-ui，未选星愿也可调）
+    // （bundle 常驻命名空间 xingyuan-pref）+ 标签页显隐（bundle 常驻命名空间 xingyuan-ui）。
+    // 两个偏好命名空间都挂在常驻层：整页由本文件无条件注册，命名空间若随 preset 懒加载
+    // 缺席，就会出现「整页可见但两项写不进去且静默失败」。
     ctx.slots.inject('settings.section', () => {
-        const scope = ctx.settingsScope.bind({ namespace: 'xingyuan' });
+        const prefscope = ctx.settingsScope.bind({ namespace: 'xingyuan-pref' });
         const uiscope = ctx.settingsScope.bind({ namespace: 'xingyuan-ui' });
-        return ctx.slots.register({ name: 'settings.section', id: 'xingyuan', order: 60, label: () => t('settings.tabLabel'), locale: XY_NS }, () => SettingsSection({ scope, uiscope }));
+        return ctx.slots.register({ name: 'settings.section', id: 'xingyuan', order: 60, label: () => t('settings.tabLabel'), locale: XY_NS }, () => SettingsSection({ scope: prefscope, uiscope }));
     });
 }

package/lib/client/pages/calendar.js

@@ -4,7 +4,7 @@ import { getJson, postAction } from '../api.js';
 import { t } from '../i18n.js';
 import { softConfirm, useActionGuard, usePageData, useStableScrollbar, localYmd } from '../hooks.js';
 import { PageError, PageSkeleton, toast } from '../ui.js';
-import { cycleLabel, dateSuffix, formatFriendlyDate, formatMonth } from './format.js';
+import { cycleLabel, dateSuffix, formatFriendlyDate, formatMonth, formatShortDate } from './format.js';
 function monthOf(offset) {
     const base = new Date();
     base.setDate(1);
@@ -66,7 +66,7 @@ export function CalendarPage() {
                     ? t('toast.claimed', { name: taskName })
                     : action === 'checkin'
                         ? t('toast.checkinOk') + dateSuffix(date)
-                        : t('toast.undoneAt', { date }), 'ok');
+                        : t('toast.undoneAt', { date: formatShortDate(date) }), 'ok');
                 // busy 窗口覆盖月历重取；之后仅当操作日仍是当前选中日才回填详情——
                 // 动作与快速连点另一日期竞争时，慢的旧响应不得覆盖新选中日的面板
                 return page.reload().then(() => {
@@ -77,7 +77,10 @@ export function CalendarPage() {
                         .then((dayAfter) => { if (seq === pickSeqRef.current) {
                         setDetail(dayAfter);
                         setPickState('idle');
-                    } });
+                    } })
+                        // 动作已成功、仅详情回取失败：转面板错误态（重试即重新拾取），不静默吞掉也不误报动作失败
+                        .catch(() => { if (seq === pickSeqRef.current)
+                        setPickState('error'); });
                 });
             }));
         };
@@ -202,7 +205,10 @@ export function CalendarPage() {
                             ...(task.wishName !== undefined ? [task.wishName] : []),
                             ...(stateText !== '' ? [stateText] : []),
                         ];
-                        return createElement('li', { key: task.taskId, className: 'xy-grouprow' }, createElement('div', { className: 'xy-rowmain' }, createElement('span', { className: 'xy-rowtitle' }, task.name), createElement('span', { className: 'xy-meta' }, segments.join(' · '))), task.status === 'pending' && !task.checked
+                        return createElement('li', { key: task.taskId, className: 'xy-grouprow' }, createElement('div', { className: 'xy-rowmain' }, createElement('span', { className: 'xy-rowtitle' }, task.name), createElement('span', { className: 'xy-meta' }, segments.join(' · '))), 
+                        // 领取仅限今日：claim 无日期语义，claimDate 恒为领取当天——
+                        // 过去/未来选中日的「领取」按钮会造出锚点与所见不符的任务
+                        task.status === 'pending' && !task.checked && detail.date === data.today
                             ? createElement('button', { className: 'xy-btn', disabled: busy, onClick: () => act('claim', task.taskId, task.name, detail.date) }, t('action.claim'))
                             : !task.checked && task.status === 'in_progress'
                                 ? createElement('button', { className: 'xy-btn xy-btn-primary', disabled: busy || !task.canCheckIn, onClick: () => act('checkin', task.taskId, task.name, detail.date) }, t('action.checkinThisDay'))