@dsh-ft/dsh-fft-settings 0.5.0 → 0.6.0

package/README.md

@@ -39,7 +39,7 @@ const apiKey = ctx.ftshareSettings.apiKey
 | `set(value)` | `Promise<void>`：只保存，不联网测试；去首尾空白，拒绝空值、超过 512 字符和控制字符 |
 | `clear()` | `Promise<void>`：只清除 DSH 保存值；可能露出 `.env` 回退值 |
 | `configureAndTest(value)` | `Promise<ConfigureResult>`：先保存，再检查远端服务和 Key；保存和验证分别返回，测试失败不回滚 |
-| `testConnection()` | `Promise<ValidationResult>`：先匿名检查远端，再验证调用时生效的 Key，不修改配置；无 Key 仍检查远端 |
+| `testConnection()` | `Promise<ValidationResult>`：先检查远端（配置了 Key 时携带），再验证调用时生效的 Key，不修改配置；无 Key 仍检查远端 |
 | `getValidationStatus()` | `Promise<ValidationResult>`：读取最近验证结果，不联网 |
 | `subscribe(listener)` | 返回取消订阅函数；失效通知，无参数、无密钥；回调重新读取状态 |
 | `createEnvironment(base?)` | 返回新环境变量对象，用当前 Key 替换 `FTSHARE_API_KEY`；无 Key 删除该字段，不修改 base |
@@ -73,9 +73,11 @@ const result = await apiKey.configureAndTest(userInput)
 
 | 结果字段 | 检测目的 | 固定请求 | 是否携带 Key |
 | --- | --- | --- | --- |
-| `validation.remote` | 远端服务是否正常 | `GET https://market.ft.tech/gateway/api/v1/market/data/stock-candlesticks` | 不携带 |
+| `validation.remote` | 远端服务是否正常 | `GET https://market.ft.tech/gateway/api/v1/market/data/stock-candlesticks` | 配置了 Key 时携带；未配置时匿名 |
 | `validation.apiKey` | 当前 Key 是否通过认证 | `GET https://market.ft.tech/gateway/api/v2/market/data/stock_minutes` | 使用 `FTSHARE_API_KEY` 请求头 |
 
+远端检查也携带 Key：网关的匿名额度按出口 IP 计（500 次／24 小时），用尽后未携带 Key 的请求一律 429。若远端检查仍走匿名，用户在已经配好可用 Key 的情况下会看到「请求受限、Key 未验证」，把 Key 问题和服务额度问题混在一起。携带 Key 后远端检查照旧只看 HTTP／业务码与 `data` 数组，认证与权限失败按下面规则归到 Key 上。
+
 日 K 请求使用 `600519.SH`、day、不复权、最近 30 天、`limit=2`；历史分钟请求使用同一股票、1 分钟、不复权、最近 24 小时、`limit=1`。服务端实际限制为包含首尾的三个北京时间自然日，而非滚动 72 小时；24 小时最多覆盖两个自然日。`adjust_kind` 使用实测接受的小写 `none`；文档中的 `None` 会被实际接口以 HTTP 400 拒绝。参数固定，不查交易日历、不回溯补数据、不验证 OHLC 字段。
 
 **成功条件是 HTTP 成功、业务 `code=200` 且 `data` 为数组；数组为空同样通过。** 本插件检查服务和认证结果，不检查行情数据完整性。HTTP 200 中的业务失败、错误响应结构不能当作成功。响应中的行情不公开返回、不持久化。
@@ -83,6 +85,7 @@ const result = await apiKey.configureAndTest(userInput)
 - 远端正常、Key 通过：`status=passed`；两项均为 `available`。
 - 远端正常、Key 无效／未配置／受限：`status=partial`；`remote` 仍为 `available`，检查 `apiKey.status` 获取原因。不能把 `partial` 当作 Key 验证通过。
 - 远端检查失败：`status=failed`；有 Key 时跳过验证，`apiKey.status=not_run`，不把服务故障归咎于 Key。
+- 远端检查携带 Key 时，其 401／403 按认证、权限、额度原因分类；400／422 仍提示参数被拒，不代表 Key 无效。未配置 Key 的匿名远端检查遇到 401／403 记 `upstream_error`（服务拒绝匿名访问），不据此指控 Key。
 - 未配置 Key：仍执行匿名远端检查，Key 项显示 `auth_required` / “未配置 API Key”，不发送分钟请求。
 - 明确的 401 认证错误显示“API Key 未通过认证”；权限、额度、限流等保留独立原因，不能一律判为 Key 无效，也不能据此宣称认证成功。
 

package/lib/client.d.ts

@@ -1,8 +1,15 @@
 import { type ApiKeyCardContext } from './features/api-key/card.js';
 export * from './core/shell.js';
+export { FREE_KEY_NOTICE_ID, FREE_KEY_NOTICE_SLOT, isViewIdle, shouldShowNotice, type FreeKeyNoticeSessionState } from './features/free-key-notice/decision.js';
+export { readNoticeSeen, writeNoticeSeen, type NoticeFlagStorage } from './features/free-key-notice/storage.js';
 /** Browser context this plugin's own client half requires. */
 export type FtshareSettingsClientContext = ApiKeyCardContext;
 export declare const inject: string[];
 export declare function apply(ctx: FtshareSettingsClientContext): void;
-/** Contribute the section shell, then the built-in cards through the slot it declares. */
+/**
+ * Contribute the settings section, its cards, and the frame-wide notice.
+ *
+ * The notice deliberately does not live in the settings page: it has to reach
+ * users who never open settings, so it takes a seat in `shell.overlay`.
+ */
 export declare function registerFtshareSettings(ctx: FtshareSettingsClientContext): void;

package/lib/client.js

@@ -6,6 +6,19 @@ window.__ModuleLoader__.load({
 		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 		let react = require("react");
 		let react_jsx_runtime = require("react/jsx-runtime");
+		/**
+		* 申请／购买 API Key 的页面。`utm_source=dsh-fft` 标记来源为本插件，站点据此归因；
+		* 卡片与一次性提示共用这一条地址，不要在别处另写一份。
+		*/
+		const FTSHARE_API_KEY_APPLY_URL = "https://ftai.chat/me/profile?tab=api-key&utm_source=dsh-fft";
+		/**
+		* 设备级「已看过免费 Key 提示」标记的 localStorage 键。
+		*
+		* 带版本号：改一次文案就把版本加一，让所有用户重新看一次，不需要让用户清缓存。
+		* 设备级语义（重启、升级都保留，跨 workspace／窗口共享）由桌面版主窗口的
+		* `dsh-app://app/` origin 私有存储提供，不写宿主的配置文件。
+		*/
+		const FREE_KEY_NOTICE_STORAGE_KEY = "dsh-fft.free-key-notice.v1";
 		const FTSHARE_CREDENTIAL_EVENTS = ["credentials/reference-updated"];
 		/** Local syntax validation, never an assertion of upstream validity. */
 		function normalizeApiKey(input) {
@@ -14,8 +27,7 @@ window.__ModuleLoader__.load({
 			if (value.length > 512 || /[\x00-\x1f\x7f]/.test(value)) throw new Error("API Key 长度不能超过 512 个字符，且不能包含控制字符");
 			return value;
 		}
-		//#endregion
-		//#region src/core/contract.ts
+		// src/core/contract.ts
 		/**
 		* Identity of the settings section that carries this plugin's cards.
 		*
@@ -44,8 +56,7 @@ window.__ModuleLoader__.load({
 		* the call itself.
 		*/
 		const FTSHARE_SETTINGS_ROUTE = "/api/ftshare-settings";
-		//#endregion
-		//#region src/features/api-key/model.ts
+		// src/features/api-key/model.ts
 		var FtshareSettingsModel = class {
 			api;
 			state = {
@@ -179,8 +190,7 @@ window.__ModuleLoader__.load({
 				not_tested: "尚未测试"
 			}[status] ?? "请查看分项结果";
 		}
-		//#endregion
-		//#region src/core/rpc-core.ts
+		// src/core/rpc-core.ts
 		/**
 		* 把一次失败的信封翻译成调用方能展示的原因。
 		*
@@ -200,8 +210,7 @@ window.__ModuleLoader__.load({
 			if (!result.ok) throw new Error(describeSettingsFailure(endpoint, result.error));
 			return result.value;
 		}
-		//#endregion
-		//#region src/features/api-key/client-api.ts
+		// src/features/api-key/client-api.ts
 		/** Browser adapter deliberately has no resolve/createEnvironment method. */
 		function createApiKeyClient(transport) {
 			async function call(method, payload = {}) {
@@ -216,8 +225,7 @@ window.__ModuleLoader__.load({
 				getValidationStatus: () => call("getValidationStatus")
 			};
 		}
-		//#endregion
-		//#region src/core/client-transport.ts
+		// src/core/client-transport.ts
 		/**
 		* Browser half of the settings transport.
 		*
@@ -245,8 +253,7 @@ window.__ModuleLoader__.load({
 				return await response.json();
 			} };
 		}
-		//#endregion
-		//#region src/features/api-key/styles.ts
+		// src/features/api-key/styles.ts
 		/**
 		* The API Key card's own styles, rendered by the card component's `<style>`.
 		*
@@ -271,8 +278,7 @@ window.__ModuleLoader__.load({
 .ftshare-settings .ftshare-error { color:var(--ftshare-error); }
 @media(max-width:540px) { .ftshare-settings .ftshare-card { padding:16px; } .ftshare-settings .ftshare-result { grid-template-columns:1fr; gap:4px; } }
 `;
-		//#endregion
-		//#region src/features/api-key/card.tsx
+		// src/features/api-key/card.tsx
 		/**
 		* Contribute the built-in API Key card through the same slot a third-party
 		* card uses. Nothing about it is privileged: same declaration, same options.
@@ -370,7 +376,7 @@ window.__ModuleLoader__.load({
 										children: "重新读取状态"
 									}),
 									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
-										href: "https://ftai.chat/me/profile?tab=api-key",
+										href: FTSHARE_API_KEY_APPLY_URL,
 										target: "_blank",
 										rel: "noreferrer",
 										children: "获取 API Key ↗"
@@ -422,8 +428,307 @@ window.__ModuleLoader__.load({
 				]
 			})] });
 		}
-		//#endregion
-		//#region src/features/logs/contract.ts
+		// src/features/free-key-notice/storage.ts
+		/**
+		* 取浏览器存储；拿不到（没有 window、被禁用）时返回 undefined。
+		* @returns 可用存储，或 undefined。
+		*/
+		function browserNoticeStorage() {
+			try {
+				const storage = globalThis.localStorage;
+				return storage === void 0 ? void 0 : {
+					getItem: (key) => storage.getItem(key),
+					setItem: (key, value) => {
+						storage.setItem(key, value);
+					}
+				};
+			} catch (_blocked) {
+				return;
+			}
+		}
+		/**
+		* 读标记。任何异常与空值都算「没看过」。
+		* @param storage - 目标存储；缺失视为没看过。
+		* @param key - 标记键。
+		* @returns 是否已看过。
+		*/
+		function readNoticeSeen(storage, key) {
+			if (storage === void 0) return false;
+			try {
+				return storage.getItem(key) === "1";
+			} catch (_blocked) {
+				return false;
+			}
+		}
+		/**
+		* 写标记。写失败不抛：提示已经显示过了，这次没记下来只是下次会再弹一次。
+		* @param storage - 目标存储；缺失时什么都不做。
+		* @param key - 标记键。
+		* @returns 是否写入成功。
+		*/
+		function writeNoticeSeen(storage, key) {
+			if (storage === void 0) return false;
+			try {
+				storage.setItem(key, "1");
+				return true;
+			} catch (_blocked) {
+				return false;
+			}
+		}
+		// src/features/free-key-notice/decision.ts
+		/**
+		* 「这条一次性提示该不该弹」的判定。
+		*
+		* 与渲染分开：判定是纯函数、零依赖，能在 Node 测试里直接钉住；渲染层只管把
+		* 模态框摆出去。三条输入里任何一条没准备好都按「不弹」处理——这是刻意的，
+		* 一次没弹只是少一次提醒，弹错一次就是打扰。
+		*/
+		/** 宿主 `shell.overlay` 槽名；这个 feature 只往这一个座位贡献。 */
+		const FREE_KEY_NOTICE_SLOT = "shell.overlay";
+		/** 条目 id：必须自己的，占用宿主的会顶掉别人的浮层。 */
+		const FREE_KEY_NOTICE_ID = "ftshare.free-key-notice";
+		/**
+		* 主视图是否停在一个空会话上（没有内容会被弹窗挡住）。
+		* @param state - 会话列表快照。
+		* @returns 是否可以安全地弹出模态框。
+		*/
+		function isViewIdle(state) {
+			if (state.phase !== "ready") return false;
+			const main = Object.values(state.byId).find((session) => (session.retainedBy?.mainView ?? 0) > 0);
+			return main === void 0 || main.blank;
+		}
+		/**
+		* 是否应当显示提示。
+		* - 已看过：不弹（设备级一次）；
+		* - Key 已配置、或状态还读不到：不弹（读不到时宁可少弹）；
+		* - 主视图被有内容的会话占着：不弹，等它空下来。
+		* @param facts - 三个输入。
+		* @returns 是否显示。
+		*/
+		function shouldShowNotice(facts) {
+			if (facts.seen) return false;
+			if (facts.configured !== false) return false;
+			return facts.viewIdle;
+		}
+		// src/features/free-key-notice/styles.ts
+		/**
+		* 一次性提示的样式：固定在左下角的非阻塞卡片。
+		*
+		* 不盖遮罩、不抢焦点——这一层（宿主的 `shell.overlay`）本身可穿透点击，
+		* 条目只有在这张卡片范围内才接收指针事件，所以卡片以外的界面照常可用。
+		* 位置用 `fixed` 而不是依赖外层布局：浮层是 `inset:0` 的绝对定位层，
+		* 条目自己决定停在哪里。
+		*
+		* 颜色全走 `--dsw-alias-*` 与 `--ft-*` 变量，深色／浅色两套调色板共用一份。
+		*/
+		const FREE_KEY_NOTICE_CSS = `
+.ftshare-free-key-notice { position:fixed; left:24px; bottom:24px; z-index:20; box-sizing:border-box; width:min(320px, calc(100vw - 48px)); padding:16px; border:0.5px solid var(--dsw-alias-border-l2,rgba(0,0,0,.1)); border-radius:var(--dsw-radius-xl,20px); background:var(--dsw-alias-bg-layer-2,#fff); color:var(--dsw-alias-label-primary,#0f1115); box-shadow:var(--dsw-elevation-prominent,0 3px 8px rgba(0,0,0,.04), 0 0 20px rgba(0,0,0,.05)); animation:ftshareNoticeIn .2s ease; }
+.ftshare-free-key-notice * { box-sizing:border-box; }
+.ftshare-free-key-notice .ftshare-free-key-head { display:flex; align-items:flex-start; justify-content:space-between; gap:8px; }
+.ftshare-free-key-notice strong { font-size:14px; font-weight:500; line-height:22px; }
+.ftshare-free-key-notice .ftshare-free-key-close { flex:none; width:22px; height:22px; display:inline-flex; align-items:center; justify-content:center; border:none; border-radius:var(--dsw-radius-sm,8px); background:transparent; color:var(--dsw-alias-label-secondary,#61666b); font:inherit; font-size:12px; line-height:1; cursor:pointer; }
+.ftshare-free-key-notice .ftshare-free-key-close:hover { background:var(--dsw-alias-bg-layer-3,#f9fafb); }
+.ftshare-free-key-notice p { margin:6px 0 14px; font-size:13px; line-height:1.6; color:var(--dsw-alias-label-secondary,#61666b); }
+.ftshare-free-key-notice .ftshare-free-key-actions { display:flex; gap:8px; }
+.ftshare-free-key-notice .ftshare-free-key-actions :is(button,a) { min-height:30px; display:inline-flex; align-items:center; justify-content:center; border-radius:var(--dsw-radius-md,12px); border:0.5px solid var(--dsw-alias-border-l4,rgba(0,0,0,.16)); padding:0 12px; font:inherit; font-size:13px; background:transparent; color:inherit; text-decoration:none; cursor:pointer; }
+/* 主入口用品牌黄的半透明底：保留 FT 的色，又不至于在左下角变成一块醒目的亮黄。
+   文字仍取正文主色（不是压在上面的深黑字），70% 在深浅两套调色板下都能读。 */
+.ftshare-free-key-notice .ftshare-free-key-actions .primary { flex:1; background:color-mix(in srgb,var(--ft-accent,#f0c433) 70%,transparent); border-color:var(--ft-accent,#f0c433); color:var(--dsw-alias-label-primary,#0f1115); font-weight:500; }
+.ftshare-free-key-notice .ftshare-free-key-actions .primary:hover { background:color-mix(in srgb,var(--ft-accent,#f0c433) 82%,transparent); }
+@keyframes ftshareNoticeIn { from { opacity:0; transform:translateY(6px); } to { opacity:1; transform:none; } }
+@media (prefers-reduced-motion: reduce) { .ftshare-free-key-notice { animation:none; } }
+`;
+		// src/features/free-key-notice/card.tsx
+		/**
+		* 一次性提示：还没配置 API Key 的用户，去获取免费的 FTShare Key。
+		*
+		* 三个设计决定：
+		*
+		* 1. **左下角、不阻塞**。它是提示，不是必须处理的阻断：不盖遮罩、不抢焦点、
+		*    不打断正在发生的事，12 秒后自己淡出（鼠标悬停时暂停计时）。用 `Modal`
+		*    会遮住整个界面，代价太大。
+		* 2. **只在确认「没配 Key」时出现**。凭据状态异步读来，没读到时一律不出现，
+		*    否则配了 Key 的用户每次启动都会被闪一下。
+		* 3. **设备级只出现一次**。首次出现就写 `localStorage` 标记（见 `./storage.ts`），
+		*    不等用户点按钮——否则自动消失后标记不落盘，下次启动又会打扰。
+		*
+		* 挂载在宿主框架级的 `shell.overlay` 槽上（`ui-layout` 的 AppFrame 常驻渲染），
+		* 不在设置页里：要触达的恰恰是从不打开设置的用户。该图层本身可穿透点击，
+		* 条目只在自己的卡片范围内接收指针事件。
+		*/
+		/** 停留时长：足够读完一句话并决定要不要去获取，又不至于一直挂在界面上。 */
+		const FREE_KEY_NOTICE_AUTO_DISMISS_MS = 12e3;
+		/**
+		* 把异步的 `configured` 摊成 uSES 快照。只在有订阅者时读一次，订阅清理时停止。
+		* @param deps - 读函数与订阅函数。
+		* @returns uSES 快照源。
+		*/
+		function useConfigured(deps) {
+			const source = (0, react.useMemo)(() => {
+				let value;
+				let stop;
+				const listeners = /* @__PURE__ */ new Set();
+				const publish = () => {
+					for (const listener of [...listeners]) listener();
+				};
+				const load = () => {
+					deps.readConfigured().then((next) => {
+						value = next;
+						publish();
+					}, () => {});
+				};
+				return {
+					getSnapshot: () => value,
+					subscribe: (listener) => {
+						listeners.add(listener);
+						if (stop === void 0) {
+							load();
+							const off = deps.subscribeConfigured(load);
+							stop = () => {
+								off();
+							};
+						}
+						return () => {
+							listeners.delete(listener);
+							if (listeners.size === 0) {
+								stop?.();
+								stop = void 0;
+							}
+						};
+					}
+				};
+			}, [deps]);
+			return (0, react.useSyncExternalStore)(source.subscribe, source.getSnapshot, source.getSnapshot);
+		}
+		/**
+		* 提示本体。
+		* @param props - 依赖注入，以及宿主通过槽位交给每个条目的标准份额。
+		* @returns 左下角卡片，或 null。
+		*/
+		function FreeKeyNotice({ deps, useSessions }) {
+			const [seen, setSeen] = (0, react.useState)(() => readNoticeSeen(deps.storage, FREE_KEY_NOTICE_STORAGE_KEY));
+			const [visible, setVisible] = (0, react.useState)(true);
+			const configured = useConfigured(deps);
+			const viewIdle = useSessions(isViewIdle);
+			const show = visible && shouldShowNotice({
+				seen,
+				configured,
+				viewIdle
+			});
+			(0, react.useEffect)(() => {
+				if (!show || seen) return;
+				writeNoticeSeen(deps.storage, FREE_KEY_NOTICE_STORAGE_KEY);
+				setSeen(true);
+			}, [
+				show,
+				seen,
+				deps.storage
+			]);
+			const deadline = (0, react.useRef)(void 0);
+			const timer = (0, react.useRef)(void 0);
+			const dismiss = (0, react.useCallback)(() => {
+				setVisible(false);
+			}, []);
+			const hold = (0, react.useCallback)(() => {
+				if (timer.current !== void 0) clearTimeout(timer.current);
+				timer.current = void 0;
+				deadline.current = void 0;
+			}, []);
+			const resume = (0, react.useCallback)(() => {
+				if (deadline.current === void 0) return;
+				const remaining = Math.max(0, deadline.current - Date.now());
+				timer.current = setTimeout(dismiss, remaining);
+			}, [dismiss]);
+			(0, react.useEffect)(() => {
+				if (!show) return;
+				deadline.current = Date.now() + FREE_KEY_NOTICE_AUTO_DISMISS_MS;
+				timer.current = setTimeout(dismiss, FREE_KEY_NOTICE_AUTO_DISMISS_MS);
+				return () => {
+					if (timer.current !== void 0) clearTimeout(timer.current);
+					timer.current = void 0;
+					deadline.current = void 0;
+				};
+			}, [show, dismiss]);
+			if (!show) return null;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: FREE_KEY_NOTICE_CSS }), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("aside", {
+				className: "ftshare-free-key-notice",
+				role: "status",
+				"aria-live": "polite",
+				onMouseEnter: hold,
+				onMouseLeave: resume,
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "ftshare-free-key-head",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("strong", { children: "免费获取 Key" }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							className: "ftshare-free-key-close",
+							"aria-label": "关闭",
+							onClick: dismiss,
+							children: "✕"
+						})]
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", { children: "海量金融数据，一次配置长期使用" }),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "ftshare-free-key-actions",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+							className: "primary",
+							href: deps.applyUrl,
+							target: "_blank",
+							rel: "noreferrer",
+							onClick: dismiss,
+							children: "去获取"
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							onClick: dismiss,
+							children: "知道了"
+						})]
+					})
+				]
+			})] });
+		}
+		/**
+		* 浏览器侧装配：把凭据通道、真实 localStorage 接到组件上。
+		* `useSessions` 是宿主交给 `shell.overlay` 条目的标准份额，从 props 透传而不是自造。
+		* @param ctx - 卡片那套上下文（slots + 凭据失效事件）。
+		* @returns 槽位组件工厂。
+		*/
+		function createFreeKeyNotice(ctx) {
+			const api = createApiKeyClient(createSettingsTransport());
+			const subscribeConfigured = (listener) => {
+				const disposers = FTSHARE_CREDENTIAL_EVENTS.map((event) => ctx.remote.$on(event, (ref) => {
+					if (ref === "FTSHARE_API_KEY") listener();
+				}));
+				disposers.push(ctx.on("connection/reset", listener));
+				return () => {
+					for (const dispose of disposers) dispose();
+				};
+			};
+			const deps = {
+				readConfigured: async () => (await api.describe()).configured,
+				subscribeConfigured,
+				storage: browserNoticeStorage(),
+				applyUrl: FTSHARE_API_KEY_APPLY_URL
+			};
+			return ({ useSessions }) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(FreeKeyNotice, {
+				deps,
+				useSessions
+			});
+		}
+		// src/features/free-key-notice/index.ts
+		/**
+		* 注册一次性提示。
+		* @param ctx - 客户端上下文，需带 `slots` 服务。
+		* @returns 幂等 disposer。
+		*/
+		function registerFreeKeyNotice(ctx) {
+			const component = createFreeKeyNotice(ctx);
+			return ctx.slots.inject(FREE_KEY_NOTICE_SLOT, () => ctx.slots.register({
+				name: FREE_KEY_NOTICE_SLOT,
+				id: FREE_KEY_NOTICE_ID,
+				order: 100
+			}, component));
+		}
+		// src/features/logs/contract.ts
 		/**
 		* `logs` 命名空间的共享契约：只有常量与类型，浏览器半边可以安全导入。
 		*
@@ -444,8 +749,7 @@ window.__ModuleLoader__.load({
 		* 它随 owner fiber 释放（`ctx.effect` + `register` 返回的 disposer）。
 		*/
 		const LOGS_ARCHIVE_ROUTE = "/api/ftshare-settings/logs.zip";
-		//#endregion
-		//#region src/features/logs/client-api.ts
+		// src/features/logs/client-api.ts
 		/** 浏览器适配器：只读，且不暴露本地路径以外的任何 Host 能力（刷盘与释放句柄）。 */
 		function createLogsClient(transport) {
 			const call = (method, payload = {}) => callSettingsRpc(transport, "logs", method, payload);
@@ -455,8 +759,7 @@ window.__ModuleLoader__.load({
 				export: () => call("export")
 			};
 		}
-		//#endregion
-		//#region src/features/logs/styles.ts
+		// src/features/logs/styles.ts
 		/**
 		* The `logs` card's own styles, rendered by the card component's `<style>`.
 		*
@@ -470,8 +773,7 @@ window.__ModuleLoader__.load({
 .ftshare-settings .ftshare-download { display:inline-flex; align-items:center; min-height:32px; padding:0 14px; border:0.5px solid var(--ftshare-control); border-radius:var(--dsw-radius-md); color:inherit; text-decoration:none; cursor:pointer; }
 .ftshare-settings .ftshare-log-preview { max-height:320px; overflow:auto; margin:0 0 12px; padding:12px; background:var(--ftshare-input); border:0.5px solid var(--ftshare-border); border-radius:var(--dsw-radius-lg); font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; line-height:1.5; white-space:pre-wrap; overflow-wrap:anywhere; }
 `;
-		//#endregion
-		//#region src/features/logs/card.tsx
+		// src/features/logs/card.tsx
 		/** 预览行数候选：上限由 Host 侧校验兜底。 */
 		const PREVIEW_CHOICES = [
 			50,
@@ -668,8 +970,7 @@ window.__ModuleLoader__.load({
 				]
 			})] });
 		}
-		//#endregion
-		//#region src/core/styles.ts
+		// src/core/styles.ts
 		/**
 		* The section shell's styles plus the theme tokens every card reads.
 		*
@@ -713,8 +1014,7 @@ window.__ModuleLoader__.load({
 .ftshare-settings a { color:var(--ftshare-link); }
 @media(max-width:540px) { .ftshare-settings header { flex-direction:column; gap:10px; } }
 `;
-		//#endregion
-		//#region src/core/shell.tsx
+		// src/core/shell.tsx
 		/** Section slot this seam contributes into; declared by the settings shell. */
 		const FTSHARE_SETTINGS_SECTION_NAME = "settings.section";
 		/**
@@ -743,8 +1043,7 @@ window.__ModuleLoader__.load({
 				} }
 			}, FtshareSettingsSection));
 		}
-		//#endregion
-		//#region src/brand.ts
+		// src/brand.ts
 		/** One value for both palettes: brand fills are scheme-invariant. */
 		const invariant = (value) => ({
 			light: value,
@@ -796,25 +1095,35 @@ window.__ModuleLoader__.load({
 				scope.effect(() => scope.theme.overrideTokens(FT_BRAND_SOURCE, FT_BRAND_TOKENS), "ft-settings: FT brand tokens");
 			});
 		}
-		//#endregion
-		//#region src/client.tsx
+		// src/client.tsx
 		const inject = ["slots", "remote"];
 		function apply(ctx) {
 			registerFtshareSettings(ctx);
 			applyBrandTokens(ctx);
 		}
-		/** Contribute the section shell, then the built-in cards through the slot it declares. */
+		/**
+		* Contribute the settings section, its cards, and the frame-wide notice.
+		*
+		* The notice deliberately does not live in the settings page: it has to reach
+		* users who never open settings, so it takes a seat in `shell.overlay`.
+		*/
 		function registerFtshareSettings(ctx) {
 			registerSettingsSection(ctx);
 			registerApiKeyCard(ctx);
 			registerLogsCard(ctx);
+			registerFreeKeyNotice(ctx);
 		}
-		//#endregion
+		exports.FREE_KEY_NOTICE_ID = FREE_KEY_NOTICE_ID;
+		exports.FREE_KEY_NOTICE_SLOT = FREE_KEY_NOTICE_SLOT;
 		exports.FtshareSettingsSection = FtshareSettingsSection;
 		exports.apply = apply;
 		exports.inject = inject;
+		exports.isViewIdle = isViewIdle;
+		exports.readNoticeSeen = readNoticeSeen;
 		exports.registerFtshareSettings = registerFtshareSettings;
 		exports.registerSettingsSection = registerSettingsSection;
+		exports.shouldShowNotice = shouldShowNotice;
+		exports.writeNoticeSeen = writeNoticeSeen;
 		return module.exports;
 	}
 });