feat: update stats store to ignore errors in fetch methods

feat: add new fields to WidgetRegistryItem interface for enhanced widget capabilities

feat: implement local API call capability in ExternalWidgetHost for widgets

fix: handle errors gracefully in WidgetWindow during resizing

feat: add timelens.apiToken configuration option to VS Code extension

docs: update localization files with new apiToken description

feat: attach API token in timelensApi for local API calls

docs: create Widget SDK v2 migration guide for developers

feat: add third-party widget template with local API call example

chore: add package.json and tsconfig.json for third-party widget template

feat: implement database encryption in Tauri backend

feat: create Widget Dev Harness page for testing third-party widgets

chore: add Vite environment types for better TypeScript support

Author: PythonSmall-Q

CHANGELOG.md

@@ -17,6 +17,19 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **Cross-platform legacy 1.x migration** — startup now detects legacy database paths on Windows, macOS, and Linux and migrates them into the default profile.
 - **Restore monitoring active state on startup** — monitor no longer defaults to active when the user had paused tracking before quitting.
 - **Backup & Restore v2 completeness** — backup packages now include app categories, usage goals, focus sessions/rules, browser ignored domains/limits, widget permissions/audit log, VS Code sessions, API tokens, and client allowlist.
+- **Automatic archive scheduler** — added background scheduler with configurable daily run hour and battery-aware toggle, plus `get_archive_scheduler_settings` / `set_archive_scheduler_settings` commands.
+- **Hot/warm/archive tiering** — archived rows are now tagged with `tier` (`warm` or `archive`) based on age relative to the retention cutoff.
+- **Historical compression** — old archived raw usage rows can be compressed into zstd blobs in `app_usage_archive_compressed`, freeing storage while preserving queryability.
+- **Restore diff summary** — backup validation now reports per-table add/update/conflict counts and settings conflicts before applying a restore.
+- **`new_profile` restore strategy** — importing a backup can create and switch to a fresh profile instead of overwriting or merging the current one.
+- **Passphrase-protected backups** — Backup v2 packages can be AES-256-GCM encrypted with a passphrase derived key (Argon2id).
+- **Database encryption at rest** — optional file-level AES-256-GCM encryption for the local SQLite database; runtime plaintext is wiped on app exit so only the encrypted file remains at rest.
+- **Database encryption commands** — added `enable_database_encryption`, `disable_database_encryption`, and `get_database_encryption_status`.
+- **Derived metrics tables** — added incremental maintenance of `app_switch_density`, `focus_streaks`, and `interruption_summary` in the monitor task and a periodic scheduler, plus `rebuild_derived_metrics` for full repair.
+- **Distraction hotspot detection** — added `get_distraction_hotspots` command and data model for ranking high-switch-density / high-fragmentation apps and time windows.
+- **Category and project comparison** — added `get_category_comparison_in_ranges` and `get_project_comparison_in_ranges` for period-over-period drill-down beyond apps.
+- **Goal risk notifications** — added `evaluate_goal_risks` and a background notifier that emits `goal-risk-alert` events and native notifications when goals are off track.
+- **Backend Focus rule automation** — moved Focus rules from frontend-only `localStorage` to the `focus_rules` table with CRUD commands and a background evaluator that auto starts/stops focus sessions.
 
 ### Changed
 

docs/WIDGET_SDK_v2_MIGRATION.md

@@ -0,0 +1,100 @@
+# Widget SDK v2 Migration Guide
+
+TimeLens 2.0.0 introduces Widget SDK v2. This guide explains the manifest version policy, capability model, and how to upgrade an existing v1 widget.
+
+## Manifest version policy
+
+- `manifest_version` is now a required top-level integer field.
+- Supported values: `1` (legacy, auto-upgraded) and `2` (current).
+- If `manifest_version > 2`, TimeLens rejects the widget with the error **"unsupported manifest version"**.
+- v1 manifests continue to load, but they are normalized to v2 internally.
+
+## Mapping legacy permissions to capabilities
+
+In v1 you declared `permissions` as method-level strings. In v2 you declare `capabilities`, which are broader security buckets. TimeLens maps between them automatically.
+
+| Legacy permission | v2 capability |
+|---|---|
+| `screen-time:read` | `read_metrics` |
+| `todo:read` | `read_metrics` |
+| `todo:write` | `write_data` |
+| `settings:write` | `write_data` |
+| `active-window:subscribe` | `automation_trigger` |
+| `local-api:call` | `local_api_call` |
+
+### Reverse mapping (capability → runtime permissions)
+
+When you declare a capability, TimeLens grants the underlying runtime permission strings so the widget channel works out of the box.
+
+| v2 capability | Runtime permissions granted |
+|---|---|
+| `read_metrics` | `screen-time:read`, `todo:read` |
+| `write_data` | `todo:write`, `settings:write` |
+| `automation_trigger` | `active-window:subscribe` |
+| `local_api_call` | `local-api:call` |
+
+## New `local-api:call` capability
+
+Widgets can now call the TimeLens local HTTP API directly through the widget channel:
+
+```js
+const result = await context.channel.localApiCall({
+  method: "GET",
+  path: "/api/screen-time/today",
+  scopes: ["screen-time:read"],
+});
+```
+
+Requirements:
+
+1. The widget manifest includes the `local_api_call` capability.
+2. The user has granted the `local-api:call` permission to this widget instance.
+3. The requested `scopes` match the endpoint being called (e.g. `screen-time:read` for `GET /api/screen-time/today`).
+
+The host automatically issues a scoped local API token and attaches it as the `X-Api-Token` header. The client ID is set to `widget-<widget_id>`, which the local API allowlist treats as a widget identity.
+
+## How to upgrade a v1 widget
+
+1. Add `"manifest_version": 2` to `manifest.json`.
+2. Replace or supplement `permissions` with `capabilities`.
+
+Before:
+
+```json
+{
+  "widget_type": "my_widget",
+  "name": "My Widget",
+  "entry": "index.js",
+  "permissions": ["screen-time:read", "active-window:subscribe"]
+}
+```
+
+After:
+
+```json
+{
+  "manifest_version": 2,
+  "widget_type": "my_widget",
+  "name": "My Widget",
+  "entry": "index.js",
+  "capabilities": ["read_metrics", "automation_trigger"],
+  "sdk_version": "2.0.0"
+}
+```
+
+3. If you want to call the local API, add `"local_api_call"` to `capabilities` and use `context.channel.localApiCall(...)`.
+4. Optional: add `csp` for a custom Content Security Policy string, or `signature` for an SHA-256 integrity check of the entry file.
+
+## Additional optional fields
+
+| Field | Type | Description |
+|---|---|---|
+| `sdk_version` | `string` | Widget SDK version the widget targets |
+| `csp` | `string` | Content Security Policy hint |
+| `signature` | `string` | Hex SHA-256 digest of the entry file for integrity verification |
+
+## Backward compatibility
+
+- TimeLens 2.0.0 still loads v1 manifests and auto-upgrades them.
+- Existing installed widgets do not need to be re-imported.
+- The Widget Dev Harness (available in dev mode) can load both v1 and v2 manifests from a local folder without installation.

examples/third-party-widget-template/README.md

@@ -4,19 +4,50 @@ This template demonstrates the minimum files required to run a third-party JS wi
 
 ## Files
 
-- `manifest.json`: widget metadata and registry declaration
+- `manifest.json`: widget metadata and registry declaration (Widget SDK v2)
 - `index.js`: ESM widget entry implementing `createWidget().mount/unmount`
+- `index.ts`: TypeScript source for the same widget (optional)
+- `package.json`: build scripts; run `npm install && npm run build` to compile `index.ts` to `dist/index.js`
+- `tsconfig.json`: TypeScript compiler options
+
+## Manifest v2
+
+```json
+{
+  "manifest_version": 2,
+  "widget_type": "sample_hello",
+  "name": "Sample Hello Widget",
+  "entry": "index.js",
+  "capabilities": ["read_metrics", "automation_trigger"]
+}
+```
+
+### Capabilities
+
+| Capability | Runtime permissions granted |
+|---|---|
+| `read_metrics` | `screen-time:read`, `todo:read` |
+| `write_data` | `todo:write`, `settings:write` |
+| `automation_trigger` | `active-window:subscribe` |
+| `local_api_call` | `local-api:call` |
 
 ## How to test
 
 1. Copy this folder to your local TimeLens app data widgets directory:
-   - `widgets/third-party-widget-template/`
+   - `widgets/sample_hello/`
 2. Start TimeLens.
-3. Open Widget Center -> Add Widgets.
+3. Open Widget Center → Add Widgets.
 4. Add `Sample Hello Widget` and open it.
 
+For faster iteration, use the Widget Dev Harness (dev mode only):
+
+1. Open Widget Center → "Dev Harness".
+2. Select this template folder.
+3. Toggle capabilities and reload instantly.
+
 ## Notes
 
-- The current prototype supports local loading only.
 - Keep `widget_type` unique across all installed widgets.
 - The entry file must be valid ESM and export `createWidget()` or `mount()`.
+- Use `context.channel.localApiCall({ method, path, scopes })` to call the TimeLens local HTTP API.
+- See `docs/WIDGET_SDK_v2_MIGRATION.md` for migration from v1 manifests.

examples/third-party-widget-template/README.zh-CN.md

@@ -4,19 +4,50 @@
 
 ## 文件说明
 
-- `manifest.json`：小组件元数据与注册声明
+- `manifest.json`：小组件元数据与注册声明（Widget SDK v2）
 - `index.js`：ESM 入口，需实现 `createWidget().mount/unmount`
+- `index.ts`：同一小组件的 TypeScript 源码（可选）
+- `package.json`：构建脚本；运行 `npm install && npm run build` 可将 `index.ts` 编译为 `dist/index.js`
+- `tsconfig.json`：TypeScript 编译选项
+
+## Manifest v2
+
+```json
+{
+  "manifest_version": 2,
+  "widget_type": "sample_hello",
+  "name": "Sample Hello Widget",
+  "entry": "index.js",
+  "capabilities": ["read_metrics", "automation_trigger"]
+}
+```
+
+### 能力（Capabilities）
+
+| 能力 | 授予的运行时权限 |
+|---|---|
+| `read_metrics` | `screen-time:read`、`todo:read` |
+| `write_data` | `todo:write`、`settings:write` |
+| `automation_trigger` | `active-window:subscribe` |
+| `local_api_call` | `local-api:call` |
 
 ## 测试步骤
 
 1. 将本目录复制到本机 TimeLens 应用数据 widgets 目录，例如：
-   - `widgets/third-party-widget-template/`
+   - `widgets/sample_hello/`
 2. 启动 TimeLens。
-3. 打开小组件中心 -> 添加小组件。
+3. 打开小组件中心 → 添加小组件。
 4. 添加 `Sample Hello Widget` 并打开。
 
+如需快速迭代，可使用小组件开发调试台（仅开发模式）：
+
+1. 打开小组件中心 → 「开发调试」。
+2. 选择本模板文件夹。
+3. 切换能力并即时重载。
+
 ## 说明
 
-- 当前雏形仅支持本地目录加载。
 - `widget_type` 必须在本地已安装小组件中唯一。
 - 入口文件必须是有效 ESM，且导出 `createWidget()` 或 `mount()`。
+- 通过 `context.channel.localApiCall({ method, path, scopes })` 调用 TimeLens 本地 HTTP API。
+- 从 v1 清单迁移请参考 `docs/WIDGET_SDK_v2_MIGRATION.md`。

examples/third-party-widget-template/index.js

@@ -1,8 +1,60 @@
+/**
+ * @typedef {Object} AppUsageSummary
+ * @property {string} app_name
+ * @property {string} exe_path
+ * @property {number} total_seconds
+ */
+
+/**
+ * @typedef {Object} ActiveWindowInfo
+ * @property {string} app_name
+ * @property {string} exe_path
+ * @property {string} window_title
+ * @property {string} timestamp
+ */
+
+/**
+ * @typedef {Object} LocalApiCallOptions
+ * @property {string} method - HTTP method, e.g. "GET" or "POST"
+ * @property {string} path - API path, e.g. "/api/screen-time/today"
+ * @property {unknown} [body] - JSON-serializable request body
+ * @property {string[]} [scopes] - Required token scopes, e.g. ["screen-time:read"]
+ */
+
+/**
+ * @typedef {Object} WidgetChannel
+ * @property {() => Promise<AppUsageSummary[]>} getTodayAppTotals
+ * @property {(start: string, end: string) => Promise<AppUsageSummary[]>} getAppTotalsInRange
+ * @property {(cb: (info: ActiveWindowInfo) => void) => Promise<() => void>} onActiveWindowChanged
+ * @property {(options: LocalApiCallOptions) => Promise<unknown>} localApiCall
+ */
+
+/**
+ * @typedef {Object} WidgetContext
+ * @property {string} widgetId
+ * @property {string} widgetType
+ * @property {WidgetChannel} channel
+ */
+
+/**
+ * Create a new widget instance.
+ * @returns {{
+ *   mount: (container: HTMLElement, context: WidgetContext) => Promise<void>,
+ *   unmount: () => Promise<void>
+ * }}
+ */
 export function createWidget() {
+  /** @type {HTMLElement | null} */
   let rootEl = null;
+  /** @type {(() => void) | null} */
   let stopListening = null;
 
   return {
+    /**
+     * Mount the widget into the provided container.
+     * @param {HTMLElement} container
+     * @param {WidgetContext} context
+     */
     async mount(container, context) {
       rootEl = document.createElement("div");
       rootEl.style.height = "100%";
@@ -23,8 +75,14 @@ export function createWidget() {
       usage.style.fontSize = "12px";
       usage.textContent = "Loading today's usage...";
 
+      const apiStatus = document.createElement("div");
+      apiStatus.style.fontSize = "11px";
+      apiStatus.style.opacity = "0.7";
+      apiStatus.textContent = "localApiCall not started";
+
       rootEl.appendChild(title);
       rootEl.appendChild(usage);
+      rootEl.appendChild(apiStatus);
       container.appendChild(rootEl);
 
       try {
@@ -36,9 +94,27 @@ export function createWidget() {
         usage.textContent = `Failed to load usage: ${String(err)}`;
       }
 
-      stopListening = await context.channel.onActiveWindowChanged((info) => {
-        title.textContent = `Sample Hello Widget · ${info.app_name || "Unknown"}`;
-      });
+      try {
+        stopListening = await context.channel.onActiveWindowChanged((info) => {
+          title.textContent = `Sample Hello Widget · ${info.app_name || "Unknown"}`;
+        });
+      } catch (err) {
+        title.textContent = `Sample Hello Widget · active window unavailable`;
+      }
+
+      // Example: call the local HTTP API through the widget bridge.
+      try {
+        const result = await context.channel.localApiCall({
+          method: "GET",
+          path: "/api/screen-time/today",
+          scopes: ["screen-time:read"],
+        });
+        const data = Array.isArray(result) ? result : [];
+        const total = data.reduce((acc, row) => acc + (row.total_seconds || 0), 0);
+        apiStatus.textContent = `localApiCall OK · ${data.length} apps · ${(total / 3600).toFixed(1)} h`;
+      } catch (err) {
+        apiStatus.textContent = `localApiCall: ${String(err)}`;
+      }
     },
 
     async unmount() {