dsh-showcase 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -4,8 +4,15 @@
 
 ## [Unreleased]
 
+后续变更将在下一版本发布前继续记录在这里。
+
+## [0.1.4] - 2026-10-04
+
 ### Fixed
 
+- 迁移到 DSH `0.2.0-rc.2` 的 SettingsForms 与 Plugins 配置槽位：主题和海报开关改用 `.volatile()` 配置及官方行配置页，保留现有 profile 选择并支持修订号冲突保护。
+- 适配 DSH `0.2` 的严格工具输出 JSON Schema，移除旧版属性级 `required` 写法；插件不再抢占 Connection 的私有 RPC 通道，避免 Web/API Gateway 冲突。
+- 将客户端入口从旧 Settings 列表迁移到 `plugins.row.config`，在 summary/page 两种视图下均保持单一、可用的配置卡。
 - Markdown-only 摘要遇到项目外部 symlink 时静默跳过越界记录，不再把外部视口标签写入文档；海报生成仍严格拒绝越界路径。
 - GitHub Actions 改用兼容 Node 24 的官方 Action 版本，避免旧运行时弃用提醒。
 - 浏览器拒绝本地存储或偏好 JSON 损坏时，离线报告保留导出时的明暗、强调色和动效设置；无效设置不会覆盖有效值。
@@ -35,6 +42,7 @@
 
 ### Changed
 
+- 更新 README 的鸽子中转站介绍，补充当前模型覆盖、订阅方式与不定期抽奖赠 Token 福利说明。
 - 加强终末地首屏主视觉：扩大公告式标题、提高等高线存在感，加入黑色结构面与斜切信号黄带，让工业编辑风格形成明确视觉峰值。
 - 终末地交付报告收敛状态色为黑 / 灰 / 信号黄，减少红绿仪表盘噪音；桌面标题、摘要和分区增加留白，移动端阶段导航改为文档流内的吸顶栏，避免遮挡 Diff 与回执。
 - 加强终末地主屏层次：将交付中继融入黑灰标题带，局部复用等高线素材，使用深色命令输出与浅色文件清单，并补充导航、回执和按钮的交互反馈。

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/DoveLi-Gu/dsh-showcase/actions/workflows/ci.yml/badge.svg)](https://github.com/DoveLi-Gu/dsh-showcase/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-111115.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-2f855a.svg)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22.19%2B%20%7C%2024%2B-2f855a.svg)](https://nodejs.org/)
 
 **把编程 Agent 的改动和测试结果，整理成可核验的中文交付报告。**
 
@@ -36,8 +36,8 @@ dsh-showcase 是一个本地运行的 DSH 插件。它读取目标项目的 Git
 
 ## 你需要什么
 
-- **必须**：已经可以运行的 DSH Web 环境；
-- **必须**：Node.js 20+ 和 npm，用于安装本仓库及运行采集 CLI；
+- **必须**：已经可以运行的 DSH Web 环境（当前插件兼容 DSH `0.2.0-rc.2` 及同一 0.2 系列）；
+- **必须**：Node.js `22.19+` 或 `24+` 和 npm，用于安装本仓库及运行采集 CLI；
 - **可选**：Git。没有 Git 时仍会生成报告，但状态会明确标为 `partial`；
 - **可选**：Playwright 或其他浏览器验收工具。截图不是后端、CLI、库项目的必需项。
 
@@ -88,7 +88,7 @@ dsh plugin --profile web add "C:\tools\dsh-showcase"
 
 然后重启 `dsh web`，再新建一个会话。若命令提示 `dsh` 不存在，先安装并确认 DSH CLI 已加入 `PATH`；这不是本插件自身的安装错误。
 
-打开 DSH 的插件设置，找到 **布局证据产物**。这里可以选择：
+打开 DSH 侧栏的 **插件**，进入 `dsh-showcase`，点击组件 `dsh-showcase/plugin` 的 **配置**，找到 **布局证据产物**。这里可以选择：
 
 - **终末地帝江号**：机械工业、密集等高线和黄黑校准色；
 - **蓝色大肥鱼**：浅蓝背景、角色主视觉和钴蓝强调；
@@ -189,6 +189,20 @@ $showcaseRepo = "C:\tools\dsh-showcase"
 
 </details>
 
+## 在 DSH 生态中被发现
+
+DeepSeek Harness 官方目前没有单独的插件提交审核页面；官方仓库建议插件作者给 GitHub 仓库添加 `dsh-plugin` Topic，用于社区发现。本仓库已经配置 `dsh-plugin`、`deepseek-harness`、`dsh` 和 `cordis` 等主题标签。
+
+部分社区插件目录会定期扫描 `dsh-plugin` Topic，并根据公开仓库的 `package.json`、`dsh.bundle.patch`、入口文件和版本信息生成卡片。收录通常存在延迟，目录属于社区项目，不代表 DeepSeek 官方背书；用户仍可直接使用 DSH 官方命令安装：
+
+~~~powershell
+dsh plugin --profile web add dsh-showcase
+~~~
+
+- 官方生态说明：[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+- 社区目录示例：[DSH Plugins Marketplace](https://github.com/bradeGithub/DSH-Plugins-Marketplace)
+- 社区展示与反馈：DeepSeek Harness 仓库的 **Show Your Plugins** Discussions
+
 ## 赞助商
 
 <div align="center">
@@ -200,12 +214,14 @@ $showcaseRepo = "C:\tools\dsh-showcase"
   <p><strong>稳定、透明、易接入的 AI API 中转服务</strong></p>
 </div>
 
-鸽子中转站（Pigeon API Relay）兼容 OpenAI API 格式，重点提供 GPT-5.6 全系列、Claude Opus 5、Fable 5 等模型，同时覆盖多种国产模型，适用于 AI 编程、客户端接入、日常对话、内容创作和图像生成等场景。
+鸽子中转站（Pigeon API Relay）兼容 OpenAI API 格式，持续跟进主流模型与可用线路。当前重点覆盖 GPT-6.1 Sol、GPT-6 Astra / Sol / Luna、GPT-5.6 全系列、GPT-5.5 / 5.4，Claude Opus 5、Fable 5、Sonnet 5，DeepSeek V4 Pro / Flash、Gemini、Grok，以及 Qwen、Kimi、GLM 等国产模型，适用于 AI 编程、Agent 工具调用、客户端接入、日常对话、内容创作和图像生成等场景。
+
+平台支持余额按量与订阅套餐两种方式，提供灵活的日卡、月卡方案；你可以在一个控制台中统一管理 API Key、模型调用、余额、用量和订阅权益，并查看模型价格、服务状态与详细接入文档。模型列表、可用线路、价格和套餐权益会随站内运营持续更新，最终以鸽子中转站实时信息为准。
 
-平台支持余额按量与订阅套餐两种方式，包含灵活的日卡、月卡方案；模型价格和套餐权益清晰可查。你可以在一个控制台中统一管理 API Key、模型调用、余额、用量和订阅权益，并查看服务状态与详细接入文档。具体模型、价格及套餐权益以鸽子中转站站内实时信息为准。
+站长也会不定期组织抽奖和用户福利，赠送 Token、体验额度或其他使用权益。活动时间、参与方式与发放规则以鸽子中转站公告为准，欢迎关注站内动态。
 
 <p align="center">
-  <code>兼容 OpenAI API</code> · <code>GPT-5.6 全系列</code> · <code>余额按量</code> · <code>日卡/月卡订阅</code>
+  <code>兼容 OpenAI API</code> · <code>GPT-6 / GPT-5.6</code> · <code>DeepSeek V4</code> · <code>余额按量</code> · <code>日卡/月卡订阅</code> · <code>不定期抽奖送 Token</code>
 </p>
 
 <p align="center">
@@ -233,8 +249,9 @@ $showcaseRepo = "C:\tools\dsh-showcase"
       </td>
       <td>
         <p><strong>稳定、透明、易接入的 AI API 中转服务，兼容 OpenAI API 格式。</strong></p>
-        <p>重点提供 GPT-5.6 全系列、Claude Opus 5、Fable 5 等模型，同时覆盖多种国产模型，适用于 AI 编程、客户端接入、日常对话、内容创作和图像生成等场景。</p>
-        <p>平台支持余额按量与订阅套餐两种方式，包含灵活的日卡、月卡方案；用户可以统一管理 API Key、模型调用、余额、用量和订阅权益，并查看模型价格、套餐权益、服务状态和详细接入文档。具体模型、价格及套餐权益以站内实时信息为准。</p>
+        <p>当前重点覆盖 GPT-6.1 Sol、GPT-6 Astra / Sol / Luna、GPT-5.6 全系列、GPT-5.5 / 5.4，Claude Opus 5、Fable 5、Sonnet 5，DeepSeek V4 Pro / Flash、Gemini、Grok，以及 Qwen、Kimi、GLM 等国产模型，适用于 AI 编程、Agent 工具调用、客户端接入、日常对话、内容创作和图像生成等场景。</p>
+        <p>平台支持余额按量与订阅套餐，提供日卡、月卡等灵活方案；用户可以统一管理 API Key、模型调用、余额、用量和订阅权益，并查看模型价格、服务状态与详细接入文档。模型列表、线路、价格和套餐权益会持续更新，最终以站内实时信息为准。</p>
+        <p><strong>不定期福利：</strong>站长会组织抽奖并赠送 Token、体验额度或其他使用权益，活动时间和参与规则以站内公告为准。</p>
       </td>
     </tr>
   </tbody>
@@ -419,7 +436,7 @@ CLI 会保留 `report.json` 中已经存在的截图记录，但不会自动启
 
 ## 从源码开发
 
-构建工具要求 Node.js 20.19+、22.12+ 或 24+，建议使用 Node.js 24。安装到 DSH 的插件运行时要求仍为 Node.js 20+。
+构建工具和 DSH `0.2` 插件运行时要求 Node.js `22.19+` 或 `24+`；建议使用 Node.js 24。DSH `0.1` 旧版运行时不再作为本版本的兼容目标。
 
 ~~~powershell
 npm ci

package/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 [打开 README.md](README.md)
 
-赞助商：**鸽子中转站（Pigeon API Relay）**。它兼容 OpenAI API 格式，提供 GPT-5.6 全系列、Claude Opus 5、Fable 5 等重点模型和多种国产模型，并支持余额按量、日卡/月卡订阅及统一权益管理；详情见主 README 快速开始后的赞助商区域。
+赞助商：**鸽子中转站（Pigeon API Relay）**。它兼容 OpenAI API 格式，当前重点覆盖 GPT-6、GPT-5.6、Claude Opus/Fable/Sonnet 5、DeepSeek V4、Gemini、Grok 及多种国产模型，并支持余额按量、日卡/月卡订阅及统一权益管理。站长还会不定期组织抽奖，赠送 Token、体验额度等福利；模型与活动详情以站内实时信息为准，完整介绍见主 README 快速开始后的赞助商区域。
 
 本项目提供两套主题：
 
@@ -15,6 +15,8 @@
 
 主题只在 DSH 插件设置里选择，目标项目不需要增加 `theme` 字段。
 
+当前兼容 DSH `0.2.0-rc.2` 及同一 0.2 系列。安装后从 DSH 侧栏进入 **插件**，打开 `dsh-showcase`，在 `dsh-showcase/plugin` 行点击 **配置**；Node.js 使用 `22.19+` 或 `24+`。旧版 DSH 0.1 不属于本版本的兼容目标。
+
 维护与发布相关文档：
 
 - [GitHub 上传与维护指南](docs/GITHUB_UPLOAD_GUIDE_ZH.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-showcase",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Local, verifiable delivery evidence reports for coding-agent work.",
   "type": "module",
   "main": "./plugin/client-host.js",
@@ -23,7 +23,7 @@
     "developer-tools"
   ],
   "engines": {
-    "node": ">=20"
+    "node": "^22.19.0 || >=24.0.0"
   },
   "packageManager": "npm@11.15.0",
   "publishConfig": {
@@ -41,11 +41,9 @@
     },
     "client": {
       "inject": [
-        "@deepseek-ai/dsh-client-connection",
         "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-runtime",
-        "@deepseek-ai/dsh-client-ui-settings",
-        "@deepseek-ai/dsh-client-ui-settings-plugins"
+        "@deepseek-ai/dsh-client-ui-plugin-manager"
       ],
       "platform": "web"
     }
@@ -89,17 +87,16 @@
     "capture": "tsx src/cli/index.ts capture"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/schemastery": "^3.18.4",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2",
+    "@deepseek-ai/cordis": "^4.0.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2",
     "@types/node": "latest",
     "@types/react": "latest",
     "@types/react-dom": "latest",

package/plugin/client.js

@@ -6,9 +6,7 @@ window.__ModuleLoader__.load({
     const React = require("react");
     const { useEffect, useRef, useState } = React;
 
-const inject = ["slots", "locale", "connection"];
-
-const RPC_CHANNEL = "/showcase-layout-summary";
+const inject = ["slots", "locale"];
 const LOCALE_NAMESPACE = "showcase.layoutSummary.settings";
 const STYLE_ID = "dsh-showcase-settings-style";
 const THEME_VALUES = ["frontier-signal", "blue-big-fish"];
@@ -16,6 +14,7 @@ const THEME_VALUES = ["frontier-signal", "blue-big-fish"];
 const messages = {
   zh: {
     title: "布局证据产物",
+    summary: "配置布局证据产物的海报主题与生成策略。",
     description: "先完成采集与测试，再在交付或视觉审核节点生成摘要；海报是可选的重产物。",
     legend: "海报风格",
     dijiang: "终末地帝江号",
@@ -36,6 +35,7 @@ const messages = {
   },
   en: {
     title: "Layout evidence artifacts",
+    summary: "Configure the poster theme and generation policy for layout evidence.",
     description: "Capture and test first, then generate at the delivery or visual-review checkpoint. The poster is optional and heavier.",
     legend: "Poster theme",
     dijiang: "Dijiang",
@@ -124,13 +124,15 @@ function installStyles() {
   document.head.append(tag);
 }
 
-function createThemeCard(rpc) {
-  return function ThemeCard({ t }) {
+function createThemeCard() {
+  return function ThemeCard({ t, form, view }) {
+    if (view === "summary") return React.createElement("span", { className: "dsh-showcase-settings__summary" }, t("summary"));
     const [theme, setTheme] = useState();
     const [generatePoster, setGeneratePoster] = useState(false);
     const [loadState, setLoadState] = useState("loading");
     const [saveState, setSaveState] = useState("idle");
     const [loadAttempt, setLoadAttempt] = useState(0);
+    const [writable, setWritable] = useState(false);
     const mountedRef = useRef(true);
     const savingRef = useRef(false);
     const choiceRefs = useRef({});
@@ -138,30 +140,32 @@ function createThemeCard(rpc) {
       let active = true;
       mountedRef.current = true;
       setLoadState("loading");
-      Promise.resolve().then(() => rpc.call(RPC_CHANNEL, "get", {})).then((result) => {
+      const sync = () => {
         if (!active) return;
-        const value = result.ok ? result.value : undefined;
+        const snapshot = form?.state;
+        const value = snapshot?.value;
         const validTheme = value?.theme === "frontier-signal" || value?.theme === "blue-big-fish";
         const validPosterSetting = value?.generatePoster === undefined || typeof value?.generatePoster === "boolean";
         if (validTheme && validPosterSetting) {
           setTheme(value.theme);
           if (typeof value.generatePoster === "boolean") setGeneratePoster(value.generatePoster);
-          setLoadState("ready");
+          setWritable(snapshot.writable === true);
+          setLoadState(snapshot.status === "ready" ? "ready" : "unavailable");
         } else {
+          setWritable(false);
           setLoadState("unavailable");
         }
-      }).catch(() => {
-        if (active) setLoadState("unavailable");
-      });
+      };
+      sync();
       return () => {
         active = false;
         mountedRef.current = false;
       };
-    }, [loadAttempt]);
+    }, [form, form?.state, loadAttempt]);
 
     if (loadState !== "ready") {
       const loading = loadState === "loading";
-      return React.createElement("li", {
+      return React.createElement("div", {
         className: "dsh-showcase-settings",
         "data-load-state": loadState,
         "aria-busy": loading,
@@ -193,25 +197,18 @@ function createThemeCard(rpc) {
             React.createElement("div", { className: "dsh-showcase-settings__loading-switch" }))));
     }
 
-    const disabled = saveState === "saving";
+    const disabled = saveState === "saving" || !writable;
     const save = async (patch, rollback = () => {}) => {
-      if (savingRef.current) return;
+      if (savingRef.current || !form?.mutate) return;
       savingRef.current = true;
       setSaveState("saving");
       try {
-        const result = await rpc.call(RPC_CHANNEL, "set", patch);
+        const snapshot = form.state;
+        const operations = Object.entries(patch).map(([path, value]) => ({ op: "set", path: [path], value }));
+        const accepted = await form.mutate(operations, snapshot.revision);
         if (!mountedRef.current) return;
-        const value = result.ok ? result.value : undefined;
-        const validTheme = value?.theme === "frontier-signal" || value?.theme === "blue-big-fish";
-        const validPosterSetting = value?.generatePoster === undefined || typeof value?.generatePoster === "boolean";
-        if (validTheme && validPosterSetting) {
-          setTheme(value.theme);
-          if (typeof value.generatePoster === "boolean") setGeneratePoster(value.generatePoster);
-          setSaveState("saved");
-        } else {
-          rollback();
-          setSaveState("failed");
-        }
+        if (!accepted) throw new Error("The configuration was rejected.");
+        setSaveState("saved");
       } catch {
         if (mountedRef.current) {
           rollback();
@@ -271,7 +268,7 @@ function createThemeCard(rpc) {
             ? t("failed")
             : "";
 
-    return React.createElement("li", {
+    return React.createElement("div", {
       className: "dsh-showcase-settings",
       "data-save-state": saveState,
       "aria-busy": disabled,
@@ -321,11 +318,10 @@ function createThemeCard(rpc) {
 function apply(ctx) {
   installStyles();
   ctx.effect(() => ctx.locale.register(LOCALE_NAMESPACE, messages), "dsh-showcase: settings locale");
-  const ThemeCard = createThemeCard(ctx.get("connection").rpc);
-  ctx.slots.inject("settings.plugin.item", () => ctx.slots.register({
-    name: "settings.plugin.item",
-    id: "showcase-layout-summary",
-    order: 30,
+  const ThemeCard = createThemeCard();
+  ctx.slots.inject("plugins.row.config", () => ctx.slots.register({
+    name: "plugins.row.config",
+    key: "dsh-showcase#showcase-layout-summary",
     locale: LOCALE_NAMESPACE,
   }, ThemeCard));
 }

package/plugin/index.d.ts

@@ -1,18 +1,31 @@
 export const name: string;
 export const inject: string[];
 export type ShowcaseTheme = "frontier-signal" | "blue-big-fish";
+export interface VolatileRef<T> {
+  get(): T;
+}
 export type ShowcaseSettings = {
-  theme: ShowcaseTheme;
-  generatePoster: boolean;
+  theme: VolatileRef<ShowcaseTheme>;
+  generatePoster: VolatileRef<boolean>;
+};
+export type ShowcaseSettingsInput = {
+  theme?: ShowcaseTheme;
+  generatePoster?: boolean;
 };
 export const SETTINGS_NAMESPACE: string;
-export const SETTINGS_RPC_CHANNEL: string;
 export const Config: {
-  (value?: { theme?: ShowcaseTheme; generatePoster?: boolean }): ShowcaseSettings;
+  (value?: ShowcaseSettingsInput): ShowcaseSettings;
   toJSON(): unknown;
 };
 export function apply(ctx: {
-  connection: { rpc: { handle(channel: string, handler: (endpoint: string, payload: unknown) => Promise<unknown>, options: { authority: "loopback" }): unknown } };
-  settings: { register(namespace: string, schema: unknown, options: { base: ShowcaseSettings }): { get(): ShowcaseSettings; update(patch: Partial<ShowcaseSettings>): Promise<void> } };
+  connection?: unknown;
+  settings: {
+    describe?(): Array<{ ns: string; value?: Partial<Record<"theme" | "generatePoster", unknown>>; revision?: number }>;
+    update?(namespace: string, patch: ShowcaseSettingsInput, expectedRevision?: number): Promise<void>;
+    register?(namespace: string, schema: unknown, options: { base: ShowcaseSettingsInput }): { get(): ShowcaseSettingsInput; update(patch: ShowcaseSettingsInput): Promise<void> };
+  };
   tools: { register(definition: unknown): void };
-}, config?: { theme?: ShowcaseTheme; generatePoster?: boolean }): void;
+  inject?: (services: string[], apply: (ctx: { settings: { configure(options: { auto?: boolean }, owner?: unknown): () => void } }) => unknown) => unknown;
+  fiber?: unknown;
+  effect?: (callback: () => unknown, label?: string) => unknown;
+}, config?: ShowcaseSettingsInput | ShowcaseSettings): void;

package/plugin/index.js

@@ -1,19 +1,22 @@
 import z from "@deepseek-ai/schemastery";
-import { settingsNamespace } from "@deepseek-ai/dsh-settings";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { generateLayoutSummary } from "./layout-summary.js";
 import { isAbsolute, resolve } from "node:path";
 
 export const name = "showcase-layout-summary";
-export const inject = ["tools", "settings", "connection"];
-export const SETTINGS_NAMESPACE = settingsNamespace("showcase-layout-summary");
-export const SETTINGS_RPC_CHANNEL = "/showcase-layout-summary";
+export const inject = ["tools", "settings"];
+// The settings service addresses forms by the profile entry id declared in
+// cordis.patch.yml. Keep this stable across plugin releases so old profiles
+// keep their selected theme and poster preference.
+export const SETTINGS_NAMESPACE = "showcase-layout-summary";
 export const Config = z.object({
   theme: z.union(["frontier-signal", "blue-big-fish"])
     .default("frontier-signal")
+    .volatile()
     .description("生成 HTML 海报时使用的视觉风格：终末地帝江号或蓝色大肥鱼。主题只从插件设置读取。"),
   generatePoster: z.boolean()
     .default(false)
+    .volatile()
     .description("是否生成自包含 HTML 海报。关闭时只生成 Markdown 摘要。"),
 });
 
@@ -21,81 +24,63 @@ const outputSchema = {
   type: "object",
   additionalProperties: false,
   properties: {
-    locale: { type: "string", required: true, enum: ["zh-CN", "en"] },
-    outputPath: { type: "string", required: true, description: "Project-relative path to the generated Markdown file." },
+    locale: { type: "string", enum: ["zh-CN", "en"], required: true },
+    outputPath: { type: "string", description: "Project-relative path to the generated Markdown file.", required: true },
     posterPath: { type: "string", description: "Project-relative path to the self-contained evidence poster when generated." },
-    posterGenerated: { type: "boolean", required: true, description: "Whether this call wrote a self-contained HTML poster." },
-    sections: { type: "array", required: true, items: { type: "string" } },
+    posterGenerated: { type: "boolean", description: "Whether this call wrote a self-contained HTML poster.", required: true },
+    sections: { type: "array", items: { type: "string" }, required: true },
     theme: { type: "string", required: true },
-    themeKey: { type: "string", required: true, enum: ["frontier-signal", "blue-big-fish"] },
-    breakpoints: { type: "array", required: true, items: { type: "string" } },
-    stages: { type: "array", required: true, items: { type: "string" } },
-    freshnessWarnings: { type: "array", required: true, items: { type: "string" } },
+    themeKey: { type: "string", enum: ["frontier-signal", "blue-big-fish"], required: true },
+    breakpoints: { type: "array", items: { type: "string" }, required: true },
+    stages: { type: "array", items: { type: "string" }, required: true },
+    freshnessWarnings: { type: "array", items: { type: "string" }, required: true },
     testCount: { type: "integer", required: true },
     redactionCount: { type: "integer", required: true },
   },
 };
 
 export function apply(ctx, config = {}) {
-  const entry = Config(config);
-  let settings;
-  let settingsRegistrationError;
-  try {
-    settings = ctx.settings.register(SETTINGS_NAMESPACE, Config, { base: entry });
-  } catch (error) {
-    // A malformed value left by an older plugin version should not prevent the
-    // tool itself from registering. Keep defaults readable and make writes
-    // fail explicitly until the host-side setting is repaired or cleared.
-    settingsRegistrationError = error instanceof Error ? error.message : String(error);
-    settings = {
-      get: () => entry,
-      async update() {
-        throw new Error(`Stored plugin settings could not be loaded: ${settingsRegistrationError}`);
-      },
-    };
+  // Cordis supplies a parsed Config whose volatile fields are stable refs. The
+  // plain-object branch keeps direct consumers and older test harnesses useful.
+  const entry = hasVolatileFields(config) ? config : Config(config);
+  const initial = {
+    theme: readConfigValue(entry.theme, "frontier-signal"),
+    generatePoster: readConfigValue(entry.generatePoster, false),
+  };
+  const legacySettings = typeof ctx.settings?.register === "function";
+  let legacyRegistrationError;
+  let legacy;
+  if (legacySettings) {
+    try {
+      legacy = ctx.settings.register(SETTINGS_NAMESPACE, Config, { base: initial });
+    } catch (error) {
+      // Keep the tool available when an older host has an invalid persisted
+      // section; the new SettingsForms service rejects the same write itself.
+      legacyRegistrationError = error instanceof Error ? error.message : String(error);
+      legacy = { get: () => initial, async update() { throw new Error(`Stored plugin settings could not be loaded: ${legacyRegistrationError}`); } };
+    }
+  }
+  if (!legacySettings && typeof ctx.inject === "function") {
+    // This plugin owns a custom Plugins-page form. Disable the generic form so
+    // DSH does not render a second, competing editor for the same fields.
+    ctx.inject(["settings"], (child) => {
+      child.effect(() => child.settings.configure({ auto: false }, ctx.fiber));
+    });
   }
   const readSettings = () => {
-    const value = settings.get?.() ?? entry;
+    const descriptor = !legacySettings && typeof ctx.settings?.describe === "function"
+      ? ctx.settings.describe().find((candidate) => candidate.ns === SETTINGS_NAMESPACE)
+      : undefined;
+    const value = legacySettings ? legacy.get?.() ?? initial : descriptor?.value ?? {
+      theme: readConfigValue(entry.theme, initial.theme),
+      generatePoster: readConfigValue(entry.generatePoster, initial.generatePoster),
+    };
     return {
-      theme: value.theme === "blue-big-fish" || value.theme === "frontier-signal" ? value.theme : entry.theme,
-      generatePoster: typeof value.generatePoster === "boolean" ? value.generatePoster : entry.generatePoster,
+      theme: value.theme === "blue-big-fish" || value.theme === "frontier-signal" ? value.theme : initial.theme,
+      generatePoster: typeof value.generatePoster === "boolean" ? value.generatePoster : initial.generatePoster,
+      revision: descriptor?.revision,
     };
   };
-  ctx.connection.rpc.handle(SETTINGS_RPC_CHANNEL, async (endpoint, payload) => {
-    if (endpoint === "get") {
-      return { ok: true, value: readSettings() };
-    }
-    if (endpoint !== "set" || typeof payload !== "object" || payload === null || Array.isArray(payload)) {
-      return { ok: false, error: { code: "bad-request", message: "Expected get or set with theme or generatePoster.", details: { issues: [] } } };
-    }
-    const unknownKeys = Object.keys(payload).filter((key) => key !== "theme" && key !== "generatePoster");
-    if (unknownKeys.length) {
-      return { ok: false, error: { code: "bad-request", message: `Unsupported settings fields: ${unknownKeys.join(", ")}.`, details: { issues: [] } } };
-    }
-    const patch = {};
-    if ("theme" in payload) {
-      const theme = payload.theme;
-      if (theme !== "frontier-signal" && theme !== "blue-big-fish") {
-        return { ok: false, error: { code: "bad-request", message: "Unsupported showcase theme.", details: { issues: [] } } };
-      }
-      patch.theme = theme;
-    }
-    if ("generatePoster" in payload) {
-      if (typeof payload.generatePoster !== "boolean") {
-        return { ok: false, error: { code: "bad-request", message: "generatePoster must be a boolean.", details: { issues: [] } } };
-      }
-      patch.generatePoster = payload.generatePoster;
-    }
-    if (!Object.keys(patch).length) {
-      return { ok: false, error: { code: "bad-request", message: "Provide theme or generatePoster to update.", details: { issues: [] } } };
-    }
-    try {
-      await settings.update(patch);
-    } catch (error) {
-      return { ok: false, error: { code: "settings-rejected", message: error instanceof Error ? error.message : String(error), details: { ns: SETTINGS_NAMESPACE } } };
-    }
-    return { ok: true, value: readSettings() };
-  }, { authority: "loopback" });
   ctx.tools.register(defineTool({
     name: "showcase_layout_summary",
     description: "Generate a local Markdown layout summary from the current .showcase/report.json checkpoint. For visual UI projects, call it once after responsive captures are ready; for non-visual projects, call it after the report and tests are ready. Partial or failed reports are valid review checkpoints, but do not call after every code edit, status check, or intermediate tweak. Markdown is the lightweight default; generate an HTML poster only when the plugin setting allows it or the user explicitly requests a poster for this call. Reads only project files, writes only inside the project, and never uploads content.",
@@ -134,3 +119,16 @@ export function apply(ctx, config = {}) {
     },
   }));
 }
+
+function hasVolatileFields(value) {
+  return value !== null && typeof value === "object" && hasVolatile(value.theme) && hasVolatile(value.generatePoster);
+}
+
+function hasVolatile(value) {
+  return value !== null && typeof value === "object" && typeof value.get === "function";
+}
+
+function readConfigValue(value, fallback) {
+  const current = hasVolatile(value) ? value.get() : value;
+  return current === undefined ? fallback : current;
+}