@lmzhen/dsh-evolution-skill-history 0.0.0 → 0.11.1

package/README.md

@@ -0,0 +1,51 @@
+# @lmzhen/dsh-evolution-skill-history
+
+The web surface for skill content history: a left-sidebar panel row (**Skill history**) that lists the versions every skill write records, and the four loopback host routes it reads.
+
+The **facts** belong to `@lmzhen/dsh-evolution-core` (which artifact a version holds, how the body chain and the support-file chain split) and the **only write** is `curator.undo`. This package maps a route to that seam and draws it; it owns no state of its own.
+
+## Where it lives
+
+Two registrations, one id (`skill-history`), because that is the sidebar's contract: `sidebar.panellist` owns the button and the layout's keyed `main` slot owns the body, dispatched by the same id.
+
+    ctx.slots.inject('sidebar.panellist', function* () {
+      yield ctx.slots.register({ name: 'sidebar.panellist', id: PANEL_ID, order: 35, label: () => t('entry.label') }, PanelIcon)
+      yield ctx.slots.register({ name: 'main', key: PANEL_ID, inject: () => ({ t, loadSkills, loadVersions, undo }) }, SkillHistoryPanel)
+    })
+
+The label is a **thunk**: the sidebar re-reads it on every projection, so a language switch follows without re-registering the row. The body receives plain callbacks through its inject face — no service handle, no subscription, and the component never sees the context.
+
+## The host routes
+
+| Method | Path | Use case |
+|---|---|---|
+| GET | `/api/dsh-evolution/skill-history/skills` | the skills that recorded at least one version, with their counts |
+| GET | `/api/dsh-evolution/skill-history/versions?name=` | the body chain and the support-file chain, split, each body row carrying its own `undoable` verdict |
+| POST | `/api/dsh-evolution/skill-history/undo` | `curator.undo(name, v?)` — the only write |
+| GET | `/api/dsh-evolution/skill-history/health` | liveness probe for the client |
+
+Every route sits behind the platform's own /api fence, kept local because the canonical implementation is not part of that package's published surface: the **socket** must be loopback (authoritative; `X-Forwarded-For` is never trusted), the **Host** header must name a loopback authority, an explicit `sec-fetch-site: cross-site` marker is refused, and an attached **Origin** must be exactly this authority.
+
+Transport refusals stay transport refusals (`403` fence, `405` method, `400` missing name / malformed or oversized body). A **business** refusal is a `200` with `{ ok: false, code, message }`, and that message is the curator's own sentence — the same one `/evolution skill undo` prints, so the two faces cannot drift.
+
+The row is **inert without a web server** (`ctx.get('webServer')`, not a declared inject): a headless profile keeps the slash commands as its entry point, and no fiber waits forever on a service that will never arrive. The curator is resolved **per request**, so a profile that mounts the routes before it answers the family's `E-302` sentence instead of throwing.
+
+## What the panel shows
+
+The selected skill's versions as two groups: **Body versions** (restorable) and **File versions** (history only, because a restore rewrites `SKILL.md`). A body row offers **Restore this version** unless it already IS the live content (the host marks those), and the button turns into an inline confirmation first. After a restore the list is read again, because the restore itself is a new version.
+
+## Build
+
+The host half builds with the family's normal `packages/evolution/scripts/build-lib.mjs`. The browser half builds with `build-client.mjs`: discovery is automatic for a package that declares `dsh.client` and ships `src/client/index.ts`, and the artifact is the module loader's lazy CJS factory (`lib/client.js`).
+
+## Model Experience
+
+This package adds **no model-visible content**: no prompt section, no tool schema, no tool result text. It therefore has no token cost and no KV-cache effect. The panel is a human surface and its routes are loopback-only.
+
+## Known limitations and deferred work
+
+- **No rendered spec.** The family's specs are Node-level and this package's client half cannot be rendered there, so the panel is covered by `tsc`, the client bundle build, the pure `tests/client-api.spec.ts` and a live pass on the installed artifact. A rendered spec (jsdom plus a driven fixture runtime) is the follow-up that would catch wiring in CI.
+- **The list shows skills with recorded versions only.** A skill that never wrote through the library has no history to browse, so it does not appear; the tree-wide listing stays with the skill catalog.
+- **No diff view.** The routes return entries, not bodies; a two-version diff would need a second read route and a client-side differ.
+- **Support-file bytes are history only.** They share the index with the body, so they are listed and labelled, but `undo` refuses them by name — the bytes stay in the blob store for a hand copy.
+- **No occupancy row.** `.history` growth is documented in the evolution-core README; showing the size in the panel would promise a cleanup path the family has not designed (a whole-library reference count belongs to the curator).

package/lib/client.js

@@ -0,0 +1,340 @@
+window.__ModuleLoader__.load({
+	id: "@lmzhen/dsh-evolution-skill-history",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react = require("react");
+		//#region src/client/api.ts
+		/**
+		* The host routes this bundle calls, and the ONE place a request is made.
+		*
+		* The paths mirror the host half's `SKILL_HISTORY_ROUTES` (a spec asserts the two sides agree). Every
+		* refusal arrives as `ok:false` plus the curator's own sentence, so the panel shows the same words the
+		* slash command prints instead of inventing a second vocabulary.
+		* @module @lmzhen/dsh-evolution-skill-history/client
+		*/
+		/** Route paths, mirrored from the host half. */
+		const HOST_ROUTES = {
+			skills: "/api/dsh-evolution/skill-history/skills",
+			versions: "/api/dsh-evolution/skill-history/versions",
+			undo: "/api/dsh-evolution/skill-history/undo"
+		};
+		/** A refusal the host reported, carrying its own sentence (the curator's, not ours). */
+		var SkillHistoryRefusal = class extends Error {};
+		/**
+		* Build the panel's face over one fetch implementation.
+		* @param fetchImpl - the fetch to use; a spec passes a stub.
+		* @returns the three callbacks the component receives through its inject face.
+		*/
+		function createSkillHistoryApi(fetchImpl = fetch) {
+			const request = async (path, init) => {
+				const response = await fetchImpl(path, init);
+				if (!response.ok) throw new SkillHistoryRefusal("HTTP " + String(response.status));
+				const body = await response.json();
+				if (body.ok !== true) throw new SkillHistoryRefusal(body.message ?? "request refused");
+				return body.data;
+			};
+			return {
+				skills: async () => await request(HOST_ROUTES.skills),
+				versions: async (name) => await request(HOST_ROUTES.versions + "?name=" + encodeURIComponent(name)),
+				undo: async (name, v) => {
+					return (await request(HOST_ROUTES.undo, {
+						method: "POST",
+						headers: { "content-type": "application/json" },
+						body: JSON.stringify(v === void 0 ? { name } : {
+							name,
+							v
+						})
+					})).message;
+				}
+			};
+		}
+		//#endregion
+		//#region src/client/messages.ts
+		/**
+		* Panel copy, in a zh/en dictionary registered through the platform's locale seat.
+		*
+		* Client copy is locale-owned: the entry label, the group headings, the actions and the status lines
+		* all resolve here, and the panel carries no literal string of its own.
+		* @module @lmzhen/dsh-evolution-skill-history/client
+		*/
+		/** The locale namespace this bundle registers. */
+		const NS = "evolution-skill-history";
+		/** Chinese dictionary. */
+		const zh = {
+			"entry.label": "技能历史",
+			title: "技能历史",
+			hint: "每次技能写入留下的内容版本。回退只改 SKILL.md 正文，标记、使用计数与策展状态不变。",
+			"group.content": "正文版本",
+			"group.support": "文件版本（不可回退）",
+			"group.support.note": "附带文件的字节与正文共用一份索引；回退不恢复它们。",
+			"empty.skills": "还没有技能留下过内容版本。",
+			"empty.versions": "这个技能还没有记录版本。",
+			loading: "读取中…",
+			refresh: "刷新",
+			undo: "回退到此版",
+			"undo.confirm": "确认回退到此版？",
+			"undo.yes": "回退",
+			"undo.no": "取消",
+			current: "当前",
+			error: "读取失败",
+			versions: "个版本"
+		};
+		/** English dictionary: the same keys, or the panel falls back to the key itself. */
+		const en = {
+			"entry.label": "Skill history",
+			title: "Skill history",
+			hint: "The content versions every skill write leaves behind. Restoring changes the SKILL.md body only: markers, usage counts and curation state stay as they are.",
+			"group.content": "Body versions",
+			"group.support": "File versions (not restorable)",
+			"group.support.note": "Support-file bytes share this index with the body; restoring the body does not bring them back.",
+			"empty.skills": "No skill has recorded a content version yet.",
+			"empty.versions": "This skill has no recorded versions.",
+			loading: "Loading…",
+			refresh: "Refresh",
+			undo: "Restore this version",
+			"undo.confirm": "Restore this version?",
+			"undo.yes": "Restore",
+			"undo.no": "Cancel",
+			current: "Current",
+			error: "Could not load",
+			versions: "versions"
+		};
+		//#endregion
+		//#region src/client/Panel.ts
+		/**
+		* The skill-history panel: the skills that recorded versions, the two chains of the selected skill,
+		* and one action per body version (restore, behind an inline confirmation).
+		*
+		* The panel owns no rule: the host reports each body row with a verdict (`undoable`) computed from
+		* the version facts in evolution-core, and the curator owns the words a refusal uses. This file is
+		* presentation plus local state — it never subscribes to anything and it never sees the context.
+		* @module @lmzhen/dsh-evolution-skill-history/client
+		*/
+		const root = {
+			display: "flex",
+			height: "100%",
+			minHeight: "0",
+			fontSize: "13px",
+			color: "var(--dsw-alias-label-primary)"
+		};
+		const aside = {
+			width: "200px",
+			flex: "0 0 200px",
+			borderRight: "1px solid var(--dsw-alias-border-l2)",
+			overflowY: "auto",
+			padding: "8px 0"
+		};
+		const main = {
+			flex: "1 1 auto",
+			minWidth: "0",
+			overflowY: "auto",
+			padding: "12px 14px"
+		};
+		const skillButton = {
+			display: "block",
+			width: "100%",
+			textAlign: "left",
+			padding: "6px 12px",
+			border: "none",
+			background: "transparent",
+			color: "inherit",
+			cursor: "pointer",
+			fontSize: "13px"
+		};
+		const skillButtonActive = {
+			...skillButton,
+			background: "var(--dsw-alias-bg-l2)",
+			fontWeight: 600
+		};
+		const heading = {
+			margin: "0 0 4px",
+			fontSize: "13px",
+			fontWeight: 600
+		};
+		const hint = {
+			margin: "0 0 10px",
+			fontSize: "12px",
+			color: "var(--dsw-alias-label-secondary)",
+			lineHeight: "1.5"
+		};
+		const row = {
+			display: "flex",
+			alignItems: "center",
+			gap: "8px",
+			padding: "4px 0",
+			borderTop: "1px solid var(--dsw-alias-border-l3)"
+		};
+		const rowMeta = {
+			flex: "1 1 auto",
+			minWidth: "0",
+			fontFamily: "var(--dsw-font-mono, monospace)",
+			fontSize: "12px",
+			whiteSpace: "nowrap",
+			overflow: "hidden",
+			textOverflow: "ellipsis"
+		};
+		const chip = {
+			flex: "0 0 auto",
+			fontSize: "11px",
+			padding: "1px 6px",
+			borderRadius: "999px",
+			border: "1px solid var(--dsw-alias-border-l2)",
+			color: "var(--dsw-alias-label-secondary)"
+		};
+		const action = {
+			flex: "0 0 auto",
+			fontSize: "12px",
+			padding: "2px 8px",
+			borderRadius: "6px",
+			border: "1px solid var(--dsw-alias-border-l2)",
+			background: "transparent",
+			color: "inherit",
+			cursor: "pointer"
+		};
+		const note = {
+			margin: "0 0 10px",
+			fontSize: "12px",
+			color: "var(--dsw-alias-label-secondary)",
+			whiteSpace: "pre-wrap"
+		};
+		/** One version row: the facts, the current/plain chip, and the restore action when the row allows it. */
+		function versionEntry(face, entry) {
+			const confirming = face.confirming === entry.v;
+			return (0, react.createElement)("div", {
+				key: String(entry.v),
+				style: row
+			}, (0, react.createElement)("span", { style: rowMeta }, "v" + String(entry.v) + "  " + entry.at + "  " + entry.action + "  " + String(entry.chars) + " chars  " + entry.hash.slice(0, 12)), entry.undoable === false ? (0, react.createElement)("span", { style: chip }, face.t("current")) : null, entry.undoable === true ? (0, react.createElement)("button", {
+				type: "button",
+				style: action,
+				onClick: () => {
+					face.restore(entry.v);
+				}
+			}, confirming ? face.t("undo.confirm") : face.t("undo")) : null);
+		}
+		/** One group: a heading, an optional note, and its rows. */
+		function group(face, title, entries, noteText) {
+			if (entries.length === 0) return null;
+			return (0, react.createElement)("section", { key: title }, (0, react.createElement)("h3", { style: heading }, title), noteText === void 0 ? null : (0, react.createElement)("p", { style: hint }, noteText), ...entries.map((entry) => versionEntry(face, entry)));
+		}
+		/**
+		* The panel body.
+		* @param face - copy, the data callbacks and the in-flight confirmation state.
+		* @returns the panel element.
+		*/
+		function SkillHistoryPanel(face) {
+			const [skills, setSkills] = (0, react.useState)([]);
+			const [selected, setSelected] = (0, react.useState)(void 0);
+			const [payload, setPayload] = (0, react.useState)(void 0);
+			const [noteText, setNoteText] = (0, react.useState)(void 0);
+			const [pending, setPending] = (0, react.useState)(void 0);
+			const failed = (error) => {
+				setNoteText(face.t("error") + ": " + (error instanceof Error ? error.message : String(error)));
+			};
+			const refresh = () => {
+				setSkills([]);
+				face.loadSkills().then(setSkills).catch(failed);
+			};
+			const open = (name) => {
+				setSelected(name);
+				setPayload(void 0);
+				setPending(void 0);
+				setNoteText(void 0);
+				face.loadVersions(name).then(setPayload).catch(failed);
+			};
+			const restore = (v) => {
+				if (selected === void 0) return;
+				if (pending !== v) {
+					setPending(v);
+					return;
+				}
+				setPending(void 0);
+				face.undo(selected, v).then((message) => {
+					setNoteText(message);
+					open(selected);
+				}).catch(failed);
+			};
+			(0, react.useEffect)(refresh, []);
+			const loaded = payload !== void 0;
+			return (0, react.createElement)("div", { style: root }, (0, react.createElement)("aside", { style: aside }, skills.length === 0 ? (0, react.createElement)("p", { style: hint }, face.t("empty.skills")) : skills.map((skill) => (0, react.createElement)("button", {
+				key: skill.name,
+				type: "button",
+				style: skill.name === selected ? skillButtonActive : skillButton,
+				onClick: () => {
+					open(skill.name);
+				}
+			}, skill.name + "  (" + String(skill.versions) + ")"))), (0, react.createElement)("div", { style: main }, (0, react.createElement)("h2", { style: heading }, face.t("title")), (0, react.createElement)("p", { style: hint }, face.t("hint")), noteText === void 0 ? null : (0, react.createElement)("p", { style: note }, noteText), selected === void 0 ? null : loaded ? null : (0, react.createElement)("p", { style: hint }, face.t("loading")), loaded ? (0, react.createElement)("div", null, group({
+				...face,
+				restore,
+				confirming: pending
+			}, face.t("group.content"), payload.content), group({
+				...face,
+				restore,
+				confirming: pending
+			}, face.t("group.support"), payload.support, face.t("group.support.note")), payload.content.length === 0 && payload.support.length === 0 ? (0, react.createElement)("p", { style: hint }, face.t("empty.versions")) : null) : null));
+		}
+		//#endregion
+		//#region src/client/seam.ts
+		/** The panel id. The icon row and the `main` body MUST share it: the sidebar resolves the body by it. */
+		const PANEL_ID = "skill-history";
+		//#endregion
+		//#region src/client/index.ts
+		/**
+		* Browser half: one left-sidebar panel row (`技能历史`) and the main-column body it opens.
+		*
+		* Two places, one id — the sidebar contract is that `sidebar.panellist` owns the button and the layout's
+		* keyed `main` slot owns the body, dispatched by that same id. The row renders only while this
+		* bundle is loaded: a deployment that drops the row loses the panel and nothing else, because every
+		* fact it shows comes from the host routes on demand.
+		* @module @lmzhen/dsh-evolution-skill-history/client
+		*/
+		/** Required client services: the slot registry and the locale seat. */
+		const inject = ["slots", "locale"];
+		/** Row order inside the global panel list (beside the platform's own rows). */
+		const PANEL_ORDER = 35;
+		/** The row's icon: the label carries the accessible name, so the glyph is decoration only. */
+		function PanelIcon() {
+			return (0, react.createElement)("span", { "aria-hidden": "true" }, "🕘");
+		}
+		/**
+		* Register the locale namespace, the panel row and the panel body.
+		* @param ctx - the client cordis context.
+		*/
+		function apply(ctx) {
+			const seam = ctx;
+			const api = createSkillHistoryApi();
+			ctx.effect(() => {
+				return seam.locale.register(NS, {
+					zh,
+					en
+				});
+			}, "evolution-skill-history: locale");
+			const t = seam.locale.bind(NS);
+			seam.slots.inject("sidebar.panellist", function* () {
+				yield seam.slots.register({
+					name: "sidebar.panellist",
+					id: PANEL_ID,
+					order: 35,
+					label: () => t("entry.label")
+				}, PanelIcon);
+				yield seam.slots.register({
+					name: "main",
+					key: PANEL_ID,
+					inject: () => ({
+						t,
+						loadSkills: api.skills,
+						loadVersions: api.versions,
+						undo: api.undo
+					})
+				}, SkillHistoryPanel);
+			});
+		}
+		//#endregion
+		exports.PANEL_ORDER = PANEL_ORDER;
+		exports.apply = apply;
+		exports.inject = inject;
+
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,269 @@
+import { contentHash, errorText, partitionVersions } from "@lmzhen/dsh-evolution-core";
+//#region lib/types/routes.js
+/**
+* The skill-history HTTP surface: four loopback routes over the curator's read/write seam.
+*
+* Layering: this module maps a route to a USE CASE and does nothing else. "Which artifact does this
+* version hold" and "how do the two chains split" live in evolution-core; the only write is
+* curator.undo. The panel never writes the skill tree itself.
+* @module @lmzhen/dsh-evolution-skill-history/routes
+*/
+/** Route paths. The client bundle mirrors these literals; a spec asserts the two sides agree. */
+const SKILL_HISTORY_ROUTES = {
+	skills: "/api/dsh-evolution/skill-history/skills",
+	versions: "/api/dsh-evolution/skill-history/versions",
+	undo: "/api/dsh-evolution/skill-history/undo",
+	health: "/api/dsh-evolution/skill-history/health"
+};
+function header(request, name) {
+	const value = request.headers[name];
+	return typeof value === "string" ? value : void 0;
+}
+/** IPv4 127/8 predicate (four decimal octets, first == 127). */
+function isIPv4Loopback(value) {
+	const parts = value.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
+function isLoopbackAddress(address) {
+	if (address === void 0) return false;
+	const normalized = address.toLowerCase();
+	if (normalized === "::1") return true;
+	if (normalized.startsWith("::ffff:")) return isIPv4Loopback(normalized.slice(7));
+	return isIPv4Loopback(normalized);
+}
+/** Whether a hostname names the loopback authority (localhost, [::1], 127/8). */
+function isLoopbackHostname(hostname) {
+	if (hostname === "localhost" || hostname === "[::1]") return true;
+	return isIPv4Loopback(hostname);
+}
+/**
+* Whether one request may enter these routes.
+*
+* The same fence the platform puts on its own /api bridge, kept local because the canonical
+* implementation (packages/client/connection/src/api-request-trust.ts) is not part of that package's
+* published surface. Rules, in order: the SOCKET must be loopback (authoritative — X-Forwarded-For is
+* never trusted), the Host header must name a loopback authority (DNS-rebinding defense), an explicit
+* cross-site marker is refused, and an attached Origin must be exactly this authority.
+* @param request - the request to judge.
+* @returns true when the request may proceed.
+*/
+function isLoopbackRequest(request) {
+	if (!isLoopbackAddress(request.socket?.remoteAddress)) return false;
+	const host = header(request, "host");
+	if (host === void 0) return false;
+	let hostUrl;
+	try {
+		hostUrl = new URL("http://" + host);
+	} catch {
+		return false;
+	}
+	if (!isLoopbackHostname(hostUrl.hostname)) return false;
+	if (header(request, "sec-fetch-site") === "cross-site") return false;
+	const origin = header(request, "origin");
+	if (origin === void 0) return true;
+	try {
+		return new URL(origin).host === hostUrl.host;
+	} catch {
+		return false;
+	}
+}
+/** Write one JSON response. The routes own their response lifecycle, so every path ends here. */
+function writeJson(res, status, value) {
+	const body = JSON.stringify(value);
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"content-length": Buffer.byteLength(body)
+	});
+	res.end(body);
+}
+/**
+* Read one JSON request body, bounded.
+* @param req - the request.
+* @returns the parsed value, or null when the body is oversized, empty, or not JSON.
+*/
+async function readJsonBody(req) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req) {
+		const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		size += buffer.byteLength;
+		if (size > 65536) return null;
+		chunks.push(buffer);
+	}
+	if (size === 0) return null;
+	try {
+		return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+	} catch {
+		return null;
+	}
+}
+/**
+* Build the four routes over the curator seam.
+* @param services - the host services the handlers read.
+* @returns the route list for ctx.webServer.register.
+*/
+function makeSkillHistoryRoutes(services) {
+	/** Run one handler body with the curator, or answer the family's E-302 sentence when it is absent. */
+	const withCurator = async (res, run) => {
+		const curator = services.getCurator();
+		if (curator === void 0) {
+			writeJson(res, 200, {
+				ok: false,
+				code: "curator-not-mounted",
+				message: errorText("e-302-curator-service-not-mounted")
+			});
+			return;
+		}
+		await run(curator);
+	};
+	/** Guard: trust fence, then method. Every refusal is a JSON body, never an empty response. */
+	const guard = (req, res, method) => {
+		if (!isLoopbackRequest(req)) {
+			writeJson(res, 403, { error: "forbidden: loopback-only" });
+			return false;
+		}
+		if (req.method !== method) {
+			writeJson(res, 405, { error: "method not allowed: " + (req.method ?? "") });
+			return false;
+		}
+		return true;
+	};
+	return [
+		{
+			kind: "exact",
+			path: SKILL_HISTORY_ROUTES.skills,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				await withCurator(res, async (curator) => {
+					const listed = await curator.skills.list();
+					const withHistory = [];
+					for (const skill of listed) {
+						const versions = await curator.skills.listVersions(skill.name);
+						if (versions.length > 0) withHistory.push({
+							name: skill.name,
+							versions: versions.length
+						});
+					}
+					writeJson(res, 200, {
+						ok: true,
+						data: withHistory
+					});
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: SKILL_HISTORY_ROUTES.versions,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				const name = new URL(req.url ?? "/", "http://loopback").searchParams.get("name")?.trim() ?? "";
+				if (name === "") {
+					writeJson(res, 400, {
+						ok: false,
+						code: "bad-request",
+						message: "name is required"
+					});
+					return;
+				}
+				await withCurator(res, async (curator) => {
+					const groups = partitionVersions(await curator.history(name));
+					const live = await curator.skills.read(name);
+					const liveHash = live === null ? null : contentHash(live);
+					writeJson(res, 200, {
+						ok: true,
+						data: {
+							content: groups.content.map((entry) => ({
+								...entry,
+								undoable: entry.hash !== liveHash
+							})),
+							support: groups.support,
+							liveHash
+						}
+					});
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: SKILL_HISTORY_ROUTES.undo,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const payload = body !== null && typeof body === "object" && !Array.isArray(body) ? body : null;
+				const name = typeof payload?.name === "string" ? payload.name.trim() : "";
+				if (name === "") {
+					writeJson(res, 400, {
+						ok: false,
+						code: "bad-request",
+						message: "name is required"
+					});
+					return;
+				}
+				const raw = payload?.v;
+				if (raw !== void 0 && (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1)) {
+					writeJson(res, 400, {
+						ok: false,
+						code: "bad-request",
+						message: "v must be a positive integer"
+					});
+					return;
+				}
+				await withCurator(res, async (curator) => {
+					const result = raw === void 0 ? await curator.undo(name) : await curator.undo(name, raw);
+					writeJson(res, 200, result.ok ? {
+						ok: true,
+						data: result
+					} : {
+						ok: false,
+						code: "undo-refused",
+						message: result.message
+					});
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: SKILL_HISTORY_ROUTES.health,
+			handler: (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				writeJson(res, 200, {
+					ok: true,
+					data: { surface: "skill-history" }
+				});
+			}
+		}
+	];
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Host half of the skill-history surface: it mounts the four loopback routes the sidebar panel reads
+* and writes, and it owns nothing else.
+*
+* The version FACTS come from evolution-core (which artifact a version holds, how the body chain and
+* the support-file chain split) and the only write is the curator's undo, so this row carries no state
+* of its own: unloading it removes the routes and leaves the feature's data untouched.
+* @module @lmzhen/dsh-evolution-skill-history
+*/
+const name = "evolution-skill-history";
+/** No declared service: the web server is OPTIONAL (a headless profile has none) and the curator is
+* resolved per request, so the row activates wherever it is installed and answers honestly where a
+* service is missing — the platform rule for optional services is ctx.get, not a waited-on inject. */
+const inject = [];
+/**
+* Mount the routes as ONE effect: the disposers run on unload and on HMR.
+* @param ctx - the host context carrying webServer and the curator.
+*/
+function apply(ctx) {
+	const webServer = ctx.get("webServer");
+	if (webServer === void 0) return;
+	ctx.effect(() => {
+		const disposers = makeSkillHistoryRoutes({ getCurator: () => ctx.get("evolutionCurator") }).map((route) => webServer.register(route));
+		return () => {
+			for (const dispose of disposers) dispose();
+		};
+	}, "evolution-skill-history: routes");
+}
+//#endregion
+export { apply, inject, name };

package/lib/types/client/Panel.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The skill-history panel: the skills that recorded versions, the two chains of the selected skill,
+ * and one action per body version (restore, behind an inline confirmation).
+ *
+ * The panel owns no rule: the host reports each body row with a verdict (`undoable`) computed from
+ * the version facts in evolution-core, and the curator owns the words a refusal uses. This file is
+ * presentation plus local state — it never subscribes to anything and it never sees the context.
+ * @module @lmzhen/dsh-evolution-skill-history/client
+ */
+import { type ReactNode } from 'react';
+import type { SkillRow, VersionsPayload } from './api.ts';
+/** The face the plugin hands the component: copy plus three callbacks, never a service handle. */
+export interface PanelFace {
+    readonly t: (key: string) => string;
+    readonly loadSkills: () => Promise<readonly SkillRow[]>;
+    readonly loadVersions: (name: string) => Promise<VersionsPayload>;
+    readonly undo: (name: string, v?: number) => Promise<string>;
+}
+/**
+ * The panel body.
+ * @param face - copy, the data callbacks and the in-flight confirmation state.
+ * @returns the panel element.
+ */
+export declare function SkillHistoryPanel(face: PanelFace): ReactNode;
+//# sourceMappingURL=Panel.d.ts.map

package/lib/types/client/api.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The host routes this bundle calls, and the ONE place a request is made.
+ *
+ * The paths mirror the host half's `SKILL_HISTORY_ROUTES` (a spec asserts the two sides agree). Every
+ * refusal arrives as `ok:false` plus the curator's own sentence, so the panel shows the same words the
+ * slash command prints instead of inventing a second vocabulary.
+ * @module @lmzhen/dsh-evolution-skill-history/client
+ */
+/** Route paths, mirrored from the host half. */
+export declare const HOST_ROUTES: {
+    readonly skills: "/api/dsh-evolution/skill-history/skills";
+    readonly versions: "/api/dsh-evolution/skill-history/versions";
+    readonly undo: "/api/dsh-evolution/skill-history/undo";
+};
+/** One recorded version, as the host reports it. */
+export interface VersionRow {
+    readonly v: number;
+    readonly at: string;
+    readonly action: string;
+    readonly hash: string;
+    readonly chars: number;
+    /** Present on body rows: false when this version already IS the live content. */
+    readonly undoable?: boolean;
+}
+/** One skill that has recorded versions. */
+export interface SkillRow {
+    readonly name: string;
+    readonly versions: number;
+}
+/** The two chains, plus the live body hash the panel marks as "current". */
+export interface VersionsPayload {
+    readonly content: readonly VersionRow[];
+    readonly support: readonly VersionRow[];
+    readonly liveHash: string | null;
+}
+/** The panel's data face: plain callbacks, no service handle. */
+export interface SkillHistoryApi {
+    readonly skills: () => Promise<readonly SkillRow[]>;
+    readonly versions: (name: string) => Promise<VersionsPayload>;
+    readonly undo: (name: string, v?: number) => Promise<string>;
+}
+/** A refusal the host reported, carrying its own sentence (the curator's, not ours). */
+export declare class SkillHistoryRefusal extends Error {
+}
+/**
+ * Build the panel's face over one fetch implementation.
+ * @param fetchImpl - the fetch to use; a spec passes a stub.
+ * @returns the three callbacks the component receives through its inject face.
+ */
+export declare function createSkillHistoryApi(fetchImpl?: typeof fetch): SkillHistoryApi;
+//# sourceMappingURL=api.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,11 @@
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+/** Required client services: the slot registry and the locale seat. */
+export declare const inject: string[];
+/** Row order inside the global panel list (beside the platform's own rows). */
+export declare const PANEL_ORDER = 35;
+/**
+ * Register the locale namespace, the panel row and the panel body.
+ * @param ctx - the client cordis context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/messages.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Panel copy, in a zh/en dictionary registered through the platform's locale seat.
+ *
+ * Client copy is locale-owned: the entry label, the group headings, the actions and the status lines
+ * all resolve here, and the panel carries no literal string of its own.
+ * @module @lmzhen/dsh-evolution-skill-history/client
+ */
+/** The locale namespace this bundle registers. */
+export declare const NS = "evolution-skill-history";
+/** Chinese dictionary. */
+export declare const zh: Record<string, string>;
+/** English dictionary: the same keys, or the panel falls back to the key itself. */
+export declare const en: Record<string, string>;
+/**
+ * One message without the locale seat (the fallback path, and what a spec reads).
+ * @param language - which dictionary to read.
+ * @param key - the message key.
+ * @returns the copy, or the key itself when neither dictionary carries it.
+ */
+export declare function message(language: 'zh' | 'en', key: string): string;
+//# sourceMappingURL=messages.d.ts.map

package/lib/types/client/seam.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Structural view of the two client seams this bundle uses: the sidebar
+ * global panel row plus the main-column body it addresses, and the locale seat.
+ *
+ * The package is distributed outside the platform repository, so it declares the seams it consumes
+ * instead of importing another plugin's values (forbidden by the client bundle purity rule) or its
+ * types (which would drag platform client sources into this project). The shapes are the shell's
+ * contract: `sidebar.panellist` takes `id`/`order`/`label` and the sidebar owns the button, while the body is the
+ * root layout's keyed `main` slot dispatched by that same id.
+ * @module @lmzhen/dsh-evolution-skill-history/client
+ */
+import type { ReactNode } from 'react';
+/** The panel id. The icon row and the `main` body MUST share it: the sidebar resolves the body by it. */
+export declare const PANEL_ID = "skill-history";
+/** Registration options for the global panel row (the sidebar's own shape). */
+export interface PanelRowOptions {
+    name: 'sidebar.panellist';
+    id: string;
+    order: number;
+    /** Lazy label: the sidebar re-reads it on every projection, so the locale can change underneath. */
+    label: () => string;
+}
+/** Registration options for the main-column body: a keyed slot dispatched by sidebar entry id. */
+export interface PanelBodyOptions {
+    name: 'main';
+    key: string;
+    /** The face handed to the component: plain data and callbacks, never a service. */
+    inject: () => unknown;
+}
+/** The locale seat: register this bundle's namespace, bind a translator. */
+export interface LocaleSeat {
+    register(namespace: string, dictionaries: {
+        zh: Record<string, string>;
+        en: Record<string, string>;
+    }): () => void;
+    bind(namespace: string): (key: string) => string;
+}
+/** The slice of the client context this plugin consumes. */
+export interface ClientSeam {
+    slots: {
+        inject(name: string, callback: () => Generator<unknown, void, unknown>): unknown;
+        register(options: PanelRowOptions | PanelBodyOptions, component: (props: never) => ReactNode): () => void;
+    };
+    locale: LocaleSeat;
+}
+//# sourceMappingURL=seam.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Host half of the skill-history surface: it mounts the four loopback routes the sidebar panel reads
+ * and writes, and it owns nothing else.
+ *
+ * The version FACTS come from evolution-core (which artifact a version holds, how the body chain and
+ * the support-file chain split) and the only write is the curator's undo, so this row carries no state
+ * of its own: unloading it removes the routes and leaves the feature's data untouched.
+ * @module @lmzhen/dsh-evolution-skill-history
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "evolution-skill-history";
+/** No declared service: the web server is OPTIONAL (a headless profile has none) and the curator is
+ * resolved per request, so the row activates wherever it is installed and answers honestly where a
+ * service is missing — the platform rule for optional services is ctx.get, not a waited-on inject. */
+export declare const inject: string[];
+/**
+ * Mount the routes as ONE effect: the disposers run on unload and on HMR.
+ * @param ctx - the host context carrying webServer and the curator.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/routes.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The skill-history HTTP surface: four loopback routes over the curator's read/write seam.
+ *
+ * Layering: this module maps a route to a USE CASE and does nothing else. "Which artifact does this
+ * version hold" and "how do the two chains split" live in evolution-core; the only write is
+ * curator.undo. The panel never writes the skill tree itself.
+ * @module @lmzhen/dsh-evolution-skill-history/routes
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+/** Route paths. The client bundle mirrors these literals; a spec asserts the two sides agree. */
+export declare const SKILL_HISTORY_ROUTES: {
+    readonly skills: "/api/dsh-evolution/skill-history/skills";
+    readonly versions: "/api/dsh-evolution/skill-history/versions";
+    readonly undo: "/api/dsh-evolution/skill-history/undo";
+    readonly health: "/api/dsh-evolution/skill-history/health";
+};
+/** Largest request body these routes accept (the undo payload is a name and a number). */
+export declare const MAX_REQUEST_BODY_BYTES: number;
+/** The request facts the trust fence reads: a Node request, or the same fields in a spec fixture. */
+export interface FenceRequest {
+    readonly headers: Record<string, string | string[] | undefined>;
+    readonly socket?: {
+        readonly remoteAddress?: string | undefined;
+    } | undefined;
+}
+/**
+ * Whether one request may enter these routes.
+ *
+ * The same fence the platform puts on its own /api bridge, kept local because the canonical
+ * implementation (packages/client/connection/src/api-request-trust.ts) is not part of that package's
+ * published surface. Rules, in order: the SOCKET must be loopback (authoritative — X-Forwarded-For is
+ * never trusted), the Host header must name a loopback authority (DNS-rebinding defense), an explicit
+ * cross-site marker is refused, and an attached Origin must be exactly this authority.
+ * @param request - the request to judge.
+ * @returns true when the request may proceed.
+ */
+export declare function isLoopbackRequest(request: FenceRequest): boolean;
+/** Write one JSON response. The routes own their response lifecycle, so every path ends here. */
+export declare function writeJson(res: ServerResponse, status: number, value: unknown): void;
+/**
+ * Read one JSON request body, bounded.
+ * @param req - the request.
+ * @returns the parsed value, or null when the body is oversized, empty, or not JSON.
+ */
+export declare function readJsonBody(req: IncomingMessage): Promise<unknown>;
+/** The curator surface the routes read: history() and the library listing, undo() as the only write. */
+export type CuratorFace = Pick<Context['evolutionCurator'], 'history' | 'undo' | 'skills'>;
+/**
+ * What the handlers resolve PER REQUEST.
+ *
+ * The curator is looked up late, not captured: a profile that mounts these routes before the curator
+ * (or without it) answers the family's own E-302 sentence instead of throwing, which is how every
+ * other optional-service consumer in this family behaves.
+ */
+export interface RouteServices {
+    readonly getCurator: () => CuratorFace | undefined;
+}
+/**
+ * Build the four routes over the curator seam.
+ * @param services - the host services the handlers read.
+ * @returns the route list for ctx.webServer.register.
+ */
+export declare function makeSkillHistoryRoutes(services: RouteServices): WebRoute[];
+//# sourceMappingURL=routes.d.ts.map

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@lmzhen/dsh-evolution-skill-history",
-  "version": "0.0.0",
-  "description": "Name-claim placeholder for the skill-history web surface (the real package is published by CI).",
-  "license": "MIT"
+  "description": "Web surface for skill content history: loopback host routes plus the sidebar panel (community build)",
+  "version": "0.11.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmzhen/dsh-evolution.git",
+    "directory": "packages/evolution-skill-history"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@lmzhen/dsh-evolution-core": "^0.11.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.5-rc.2",
+    "react": "^18.2.0",
+    "@lmzhen/dsh-evolution-curator": "^0.11.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.5-rc.2",
+    "@lmzhen/dsh-evolution-core": "^0.11.1",
+    "@lmzhen/dsh-evolution-curator": "^0.11.1",
+    "@lmzhen/dsh-evolution-io": "^0.11.1",
+    "@lmzhen/dsh-evolution-io-node": "^0.11.1"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-locale"
+      ]
+    }
+  }
 }