@lmzhen/dsh-evolution-skill-history 0.14.0 → 0.15.0

package/lib/index.js

@@ -1,4 +1,4 @@
-import { contentHash, elapsedSince, errorText, latestVersionAt, partitionVersions, textDiffFacts, versionActionKind } from "@lmzhen/dsh-evolution-core";
+import { contentHash, displayBodyOf, elapsedSince, errorText, latestVersionAt, partitionVersions, skillRowCells, textDiffFacts, versionActionKind, versionRowCells } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/routes.js
 /**
 * The skill-history HTTP surface: six loopback routes over the curator's read/write seam (five reads plus the one write).
@@ -150,7 +150,7 @@ function makeSkillHistoryRoutes(services) {
 						const versions = await curator.skills.listVersions(skill.name);
 						if (versions.length === 0) continue;
 						const lastAt = latestVersionAt(versions);
-						withHistory.push({
+						const row = {
 							name: skill.name,
 							versions: versions.length,
 							description: skill.description,
@@ -159,6 +159,10 @@ function makeSkillHistoryRoutes(services) {
 							protectionUnknown: skill.protectionUnknown,
 							lastAt,
 							age: lastAt === null ? null : elapsedSince(lastAt, now)
+						};
+						withHistory.push({
+							...row,
+							cells: skillRowCells(row)
 						});
 					}
 					writeJson(res, 200, {
@@ -199,11 +203,23 @@ function makeSkillHistoryRoutes(services) {
 					writeJson(res, 200, {
 						ok: true,
 						data: {
-							content: groups.content.map((entry, index) => ({
-								...decorate(entry, index, groups.content, true),
-								undoable: entry.hash !== liveHash
-							})),
-							support: groups.support.map((entry, index) => decorate(entry, index, groups.support, false)),
+							content: groups.content.map((entry, index) => {
+								const row = {
+									...decorate(entry, index, groups.content, true),
+									undoable: entry.hash !== liveHash
+								};
+								return {
+									...row,
+									cells: versionRowCells(row)
+								};
+							}),
+							support: groups.support.map((entry, index) => {
+								const row = decorate(entry, index, groups.support, false);
+								return {
+									...row,
+									cells: versionRowCells(row)
+								};
+							}),
 							liveHash
 						}
 					});
@@ -294,7 +310,7 @@ function makeSkillHistoryRoutes(services) {
 						ok: true,
 						data: {
 							v,
-							text: truncated ? text.slice(0, MAX_BODY_CHARS) : text,
+							display: displayBodyOf(truncated ? text.slice(0, MAX_BODY_CHARS) : text),
 							chars: text.length,
 							truncated
 						}

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

@@ -1,33 +1,27 @@
 /**
- * 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: one read, one open skill, one open row — and the faces that draw them.
  *
- * The panel owns no rule and no arithmetic: the host reports each row with its whole verdict
- * (`undoable`, the vocabulary key `actionKind`, the `age` bucket, `charsDelta`, `summary`) and this
- * file substitutes WORDS through the locale dictionary and renders. It never subscribes to anything
- * and never sees the context.
- *
- * State rules, each pinned by a live pass or a component spec: a restore's result sentence stays on
- * screen while the rows are read again; nothing is read on a poll (mount, opening a skill, the
- * refresh button, after a restore); a late reply for a skill the operator has already left is
- * discarded by its ticket; and the diff is fetched only when a row is expanded.
+ * Everything a PERSON reads is decided elsewhere: what a row says is core's (`skill-row-cells.ts`,
+ * shipped with the row), the words are the dictionary's, the tool face is `chrome.ts` and the reading
+ * face is `document.ts`. What is left here is the STATE — which skill is open, which row is expanded,
+ * which reads are in flight — and the two rules that only a state machine can hold: a read takes a
+ * ticket so a slow reply cannot land on another skill, and a write reports its own result instead of
+ * being erased by the read that follows it.
  * @module @lmzhen/dsh-evolution-skill-history/client
  */
 import { type ReactNode } from 'react';
+import { type Copy } from './chrome.ts';
 import type { SkillRow, VersionBodyRow, VersionDiffRow, VersionsPayload } from './api.ts';
-import { type MarkdownWords } from './markdown.ts';
-/** The face the plugin hands the component: copy plus callbacks, never a service handle. */
-export interface PanelFace {
-    readonly t: (key: string) => string;
-    /** Fill one copy key's `{n}` slots (the dictionaries own the sentences). */
-    readonly format: (key: string, values: Record<string, string | number>) => string;
+import type { MarkdownWords } from './markdown.ts';
+/** What the panel is handed: the dictionary seat, the renderer's words, and the host's callbacks. */
+export interface PanelFace extends Copy {
+    /** The two words the platform Markdown renderer needs; the dictionary owns them. */
+    readonly markdownWords: MarkdownWords;
     readonly loadSkills: () => Promise<readonly SkillRow[]>;
     readonly loadVersions: (name: string) => Promise<VersionsPayload>;
     readonly loadDiff: (name: string, v: number) => Promise<VersionDiffRow>;
     readonly loadBody: (name: string, v: number) => Promise<VersionBodyRow>;
     readonly undo: (name: string, v?: number) => Promise<string>;
-    /** The two words the platform Markdown renderer needs; the dictionary owns them. */
-    readonly markdownWords: MarkdownWords;
 }
 /**
  * The panel body.

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

@@ -30,6 +30,30 @@ export interface VersionDiffRow {
     readonly hunks: readonly DiffHunkRow[];
     readonly truncated: boolean;
 }
+/** Where a cell sits in its row: `aside` is right-aligned and is never truncated. */
+export type CellSlot = 'lead' | 'meta' | 'aside';
+/** The visual register a cell speaks in; the stylesheet maps it to a scale token. */
+export type CellTone = 'primary' | 'secondary' | 'tertiary';
+/** One cell of a row: a locale key with the values its template needs, or a verbatim fact. */
+export type RowCell = {
+    readonly key: string;
+    readonly slot: CellSlot;
+    readonly tone: CellTone;
+    readonly note?: string;
+    readonly copy: string;
+    readonly values?: Readonly<Record<string, string | number>>;
+} | {
+    readonly key: string;
+    readonly slot: CellSlot;
+    readonly tone: CellTone;
+    readonly note?: string;
+    readonly literal: string;
+};
+/** The lines one row shows: a title line, and a meta line under it. */
+export interface RowCells {
+    readonly title: readonly RowCell[];
+    readonly meta: readonly RowCell[];
+}
 /** One recorded version, as the host reports it. */
 export interface VersionRow {
     readonly v: number;
@@ -48,6 +72,8 @@ export interface VersionRow {
         readonly unit: string;
         readonly n: number;
     };
+    /** What this row says and where each fact sits, decided in core (`skill-row-cells.ts`). */
+    readonly cells: RowCells;
     /** The one line the optional summarizer wrote, when the deployment turned it on. */
     readonly summary?: string;
     /**
@@ -71,12 +97,17 @@ export interface SkillRow {
         readonly unit: string;
         readonly n: number;
     } | null;
+    /** What this row says and where each fact sits, decided in core (`skill-row-cells.ts`). */
+    readonly cells: RowCells;
 }
 /** One version's whole body, as the read route hands it over. */
 export interface VersionBodyRow {
     readonly v: number;
-    /** The body, or its head when `truncated` — the reader is told rather than silently cut. */
-    readonly text: string;
+    /**
+     * The text a READER sees: the body without its frontmatter block, or its head when `truncated` —
+     * the reader is told rather than silently cut. The exact bytes are the diff route's answer.
+     */
+    readonly display: string;
     /** How long the stored body is, whatever came back. */
     readonly chars: number;
     readonly truncated: boolean;

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

@@ -0,0 +1,73 @@
+/**
+ * The four atoms the panel's tool face is built from (G3, §15.2 L2a atoms).
+ *
+ * Why atoms at all: the row used to be assembled from five different elements that each wrote their
+ * own classes, so "what a control looks like" was spread over the stylesheet and a click target, a
+ * state chip, a refusal and a glyph had no vocabulary at all (W7/W9/W13/W14). Every interactive
+ * element now says what it IS — a control that acts, a control that only reveals more, a state, a
+ * notice — and the stylesheet answers once per kind.
+ *
+ * No words live here: an atom takes the copy its caller already resolved.
+ * @module @lmzhen/dsh-evolution-skill-history/client
+ */
+import { type ReactNode } from 'react';
+/** The register one control speaks in. `primary` is reserved for the click that writes. */
+export type Tone = 'quiet' | 'primary';
+/**
+ * What a control DOES, which is what makes them distinguishable at a glance: one acts, one reveals
+ * more (and shows whether it is open), one chooses between two views of the same thing.
+ */
+export type ControlKind = 'action' | 'toggle' | 'switch';
+/** The glyphs the panel draws. The platform's own arrows are text characters, which render in the
+ * reader's fallback font at whatever weight it has (W7); a drawn path cannot. */
+export type IconName = 'chevron-right' | 'chevron-down' | 'alert';
+/**
+ * One drawn glyph.
+ * @param name - which glyph.
+ * @returns an inline SVG that takes the surrounding colour and type size.
+ */
+export declare function icon(name: IconName): ReactNode;
+/** What every atom takes. */
+interface BaseProps {
+    /** React key, for the callers that build lists. */
+    readonly key?: string;
+    /** The copy, already resolved by the dictionary seat. */
+    readonly children: ReactNode;
+}
+/** One control. `kind` says whether it acts or only reveals; `tone` says whether it writes. */
+export interface ButtonProps extends BaseProps {
+    readonly kind?: ControlKind;
+    readonly tone?: Tone;
+    /** Hover text, when the label alone is ambiguous. */
+    readonly title?: string;
+    /** Whether the thing this control reveals is currently open (`aria-expanded`). */
+    readonly expanded?: boolean;
+    /** Whether this control is the side of a two-way choice that is showing. */
+    readonly pressed?: boolean;
+    readonly onClick: () => void;
+}
+/**
+ * One control.
+ * @param props - what it is, how it speaks, and what it does.
+ * @returns the button element.
+ */
+export declare function button(props: ButtonProps): ReactNode;
+/**
+ * One state, spelled as a chip: never clickable, never in the primary colour (W9).
+ * @param props - the copy.
+ * @returns the chip element.
+ */
+export declare function chip(props: BaseProps): ReactNode;
+/** One notice: a sentence about what just happened, or why nothing did. */
+export interface NoteProps extends BaseProps {
+    /** Whether this is a refusal or a failure, which colours it and adds the glyph (W13). */
+    readonly error?: boolean;
+}
+/**
+ * One notice.
+ * @param props - the copy, and whether it reports a failure.
+ * @returns the note element.
+ */
+export declare function note(props: NoteProps): ReactNode;
+export {};
+//# sourceMappingURL=atoms.d.ts.map

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

@@ -0,0 +1,73 @@
+/**
+ * The TOOL face: the skill list, the version list, and the controls that act on a version.
+ *
+ * This file renders FACTS. What a row says, in which order and in which slot is decided in core
+ * (`skill-row-cells.ts`) and travels with the row, because a browser half cannot import core at
+ * runtime; the words come from the locale dictionary through the `Copy` seat. The renderer's only
+ * judgements are layout: a cell's slot decides its alignment, and the `aside` slot is the one the
+ * browser's ellipsis may never eat (W1).
+ *
+ * The reading face — a version rendered as a document, and the rendered diff — lives in
+ * `document.ts`; the two faces share the scale in `tokens.ts` and nothing else (§15.2 L2b).
+ * @module @lmzhen/dsh-evolution-skill-history/client
+ */
+import { type ReactNode } from 'react';
+import type { SkillRow, VersionRow } from './api.ts';
+/** What a chrome builder needs: the dictionary, and nothing else. */
+export interface Copy {
+    readonly t: (key: string) => string;
+    readonly format: (key: string, values: Record<string, string | number>) => string;
+}
+/** One kind of expansion a row can show. */
+export type OpenKind = 'diff' | 'preview';
+/** The local time an ISO timestamp names, as the operator's own clock shows it. */
+export declare function localTime(at: string): string;
+/** The search field above the list. */
+export declare function searchField(copy: Copy, query: string, onQuery: (value: string) => void): ReactNode;
+/**
+ * One skill in the left column: its name and size, then what it is and when it last changed.
+ * @param copy - the dictionary seat.
+ * @param row - the skill's facts and cells.
+ * @param selected - whether this is the open skill.
+ * @param onOpen - what a click does.
+ * @returns the row.
+ */
+export declare function skillLine(copy: Copy, row: SkillRow, selected: boolean, onOpen: () => void): ReactNode;
+/** What one version row needs from the panel's state machine. */
+export interface VersionRowProps {
+    readonly copy: Copy;
+    readonly row: VersionRow;
+    /** Whether this row is the one waiting for a confirmation click. */
+    readonly confirming: boolean;
+    /** Which expansion this row currently shows, if any. */
+    readonly open: OpenKind | undefined;
+    /** The expanded content, already built by the caller. */
+    readonly expanded: ReactNode;
+    readonly onRestore: () => void;
+    readonly onCancel: () => void;
+    readonly onToggle: (kind: OpenKind) => void;
+}
+/**
+ * One version row: what happened, when, how big — then the controls, then whatever is expanded.
+ *
+ * The write is the only control that can change anything, and it is the only one that ever takes the
+ * primary tone; a toggle that merely reveals more is borderless and carries a drawn chevron, so the
+ * two kinds cannot be mistaken for each other (W7/W14).
+ * @param props - the row, the copy, and the panel's callbacks.
+ * @returns the row.
+ */
+export declare function versionRow(props: VersionRowProps): ReactNode;
+/**
+ * One group's heading, and the note that explains the group.
+ * @param title - the group's name, already resolved.
+ * @param noteText - the group's note, when it has one.
+ * @returns the heading and the note, for the caller to place in its own section.
+ */
+export declare function groupHeading(title: string, noteText: string | undefined): ReactNode[];
+/** What the list shows when it has nothing to show. */
+export declare function emptyState(text: string): ReactNode;
+/** One notice about what just happened. */
+export declare function notice(text: string | undefined, error: boolean): ReactNode;
+/** The pane's heading and its one control. */
+export declare function panelHead(copy: Copy, onRefresh: () => void): ReactNode;
+//# sourceMappingURL=chrome.d.ts.map

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

@@ -0,0 +1,71 @@
+/**
+ * The READING face: one version rendered as a document, and the rendered diff.
+ *
+ * This file is the only place that decides how a document reads (G4). The tool face (`chrome.ts`)
+ * picks versions and acts on them; here the rules are the reader's, and they follow the positioning
+ * ruling of §14.0: a document is read, not scanned — one measure, page-like spacing, no inner scroll
+ * (W18/W20/W21/W22). Nothing here is a control except the source/rendered choice, which belongs to
+ * the reader rather than to the panel's actions.
+ *
+ * The text arrives already prepared: the host strips the frontmatter block through core's
+ * `displayBodyOf`, because a browser half cannot import core. The RENDERED DIFF keeps the whole text
+ * on purpose — a diff is about what CHANGED, and a metadata change is a change.
+ *
+ * It degrades rather than blanking: when the platform's renderer cannot be reached, the exact text is
+ * shown instead, and the reader can still read the version.
+ * @module @lmzhen/dsh-evolution-skill-history/client
+ */
+import { type ReactNode } from 'react';
+import type { VersionBodyRow, VersionDiffRow } from './api.ts';
+import type { Copy } from './chrome.ts';
+import { type MarkdownWords } from './markdown.ts';
+/** What one expanded diff holds: the change, still loading, or a refusal. */
+export type DiffState = {
+    kind: 'loading';
+} | {
+    kind: 'ready';
+    diff: VersionDiffRow;
+} | {
+    kind: 'failed';
+    message: string;
+};
+/** What one expanded preview holds. */
+export type BodyState = {
+    kind: 'loading';
+} | {
+    kind: 'ready';
+    body: VersionBodyRow;
+} | {
+    kind: 'failed';
+    message: string;
+};
+/** What the reading face needs: the dictionary seat, plus the two words the platform renderer takes. */
+export interface DocumentFace extends Copy {
+    readonly markdownWords: MarkdownWords;
+}
+/**
+ * One version read as a document: the platform renderer when it is there, plain text when it is not.
+ *
+ * The document is the page, not a card inside it: no border, no surface of its own and no inner
+ * scroll, so the pane's own scrollbar is the only one a reader meets (W20/W21). A body the host
+ * bounded says how much it is not showing, with both numbers (W23).
+ * @param props - the face and the body state to draw.
+ * @returns the element.
+ */
+export declare function PreviewBody(props: {
+    face: DocumentFace;
+    body: BodyState;
+}): ReactNode;
+/**
+ * The expanded body of one row: the diff, a loading line, or the refusal.
+ *
+ * The source/rendered choice is LOCAL to this view: which row is open is the panel's business, but
+ * how one open diff is displayed is not, so the state does not climb into the parent.
+ * @param props - the face and the diff state to draw.
+ * @returns the element.
+ */
+export declare function DiffBody(props: {
+    face: DocumentFace;
+    diff: DiffState;
+}): ReactNode;
+//# sourceMappingURL=document.d.ts.map

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

@@ -5,6 +5,23 @@ export interface MarkdownWords {
     /** The heading of the generated footnote section. */
     readonly footnotes: string;
 }
+/** Copy-button labels forwarded to fenced code blocks. */
+interface MarkdownCodeLabels {
+    copyLabel: string;
+    copiedLabel: string;
+}
+/** Localized Markdown chrome: every field the platform component requires. */
+interface MarkdownLabels {
+    code: MarkdownCodeLabels;
+    footnotes: string;
+}
+/** What the renderer reads; the streaming and mention knobs are not used by this panel. */
+interface MarkdownTextProps {
+    text: string;
+    labels: MarkdownLabels;
+}
+/** The component as the module table hands it over. */
+type MarkdownTextComponent = (props: MarkdownTextProps) => unknown;
 /** One render attempt: the element, or the news that this deployment has no renderer. */
 export type MarkdownRender = {
     readonly ok: true;
@@ -12,6 +29,21 @@ export type MarkdownRender = {
 } | {
     readonly ok: false;
 };
+/**
+ * The renderer a module row carries, when it carries one.
+ *
+ * A React component type is NOT always a function: the platform's own `MarkdownText` is
+ * `memo(function MarkdownText …)`, and `memo` returns an OBJECT. A `typeof === 'function'` test
+ * therefore rejected the real renderer and silently degraded every view to its source — exactly
+ * what 0.14.0 shipped (measured on the installed panel 2026-09-28: `[预览]` and the rendered diff
+ * both fell back). The accepted domain is React's element-type domain: a function, or a non-null
+ * object it can mount. `tests/markdown.client.spec.ts` pins all four cases.
+ * @param row - what the client module table handed over.
+ * @returns the component, or undefined when the row carries none.
+ */
+export declare function rendererOf(row: {
+    MarkdownText?: unknown;
+}): MarkdownTextComponent | undefined;
 /**
  * Render one Markdown document to an element tree.
  * @param text - the Markdown source (already bounded by the caller).
@@ -20,4 +52,5 @@ export type MarkdownRender = {
  *   then keeps its own source view: a missing renderer degrades the view, never the panel).
  */
 export declare function renderMarkdown(text: string, words: MarkdownWords): MarkdownRender;
+export {};
 //# sourceMappingURL=markdown.d.ts.map

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

@@ -1,24 +1,3 @@
-/**
- * The panel’s stylesheet, injected once behind a `<style data-plugin-css=…>` tag.
- *
- * The bundle is built outside the platform’s CSS-Modules pipeline, so it carries its own string and
- * injects it the same way the family’s settings section does. Every rule reads the platform’s design
- * tokens, and the metrics are COPIED from the platform’s own components rather than invented:
- *
- * - the code block (`--dsw-font-markdown-code-block-small`, `.5px` border, `12px`, radius `12px`,
- *   `max-height: 260px`) is the platform command card’s `<pre>` (client/ui-chat/…/GenericCommandCard.module.css);
- * - hover / focus (`--dsw-alias-interactive-bg-hover`, a 2px inset focus ring) follow the platform
- *   sidebar row (client/ui-sidebar/…/SidebarRoot.module.css);
- * - the panel’s type scale is the platform TOKEN rather than a magic number, so it follows the
- *   deployment’s content size the way the platform’s own panels do;
- * - the capsule and the field metrics follow the family’s settings card, which copied them from the
- *   platform’s settings fields in the first place.
- *
- * Geometry (widths, paddings, radii, the 260px scroll cap) is a plain number here because the platform's
- * own components write geometry the same way; what must never be a literal is TYPE and COLOUR, and
- * every size and colour below is a token or a `calc()` over one.
- * @module @lmzhen/dsh-evolution-skill-history/client
- */
 /** Tag id that makes the injection idempotent. */
 export declare const CSS_TAG_ID = "@lmzhen/dsh-evolution-skill-history/panel.css";
 /** The stylesheet the panel injects once. */

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

@@ -0,0 +1,25 @@
+/**
+ * The family client scale - GENERATED from packages/scripts/client-tokens.json. Do not edit.
+ *
+ * Both browser halves of the family carry this file with identical bytes, because the scale is one
+ * fact: `verify-client-tokens.mjs` (a gate step) fails when either copy drifts from the source. The
+ * scale cannot be shared at runtime - a browser half may not import evolution-core, since every
+ * `@deepseek-ai/*` specifier stays external in the client build and the platform module table has no
+ * row for it - so the values are generated into each package instead.
+ *
+ * Usage: put `tokenVars(...)` for your root class in the package stylesheet, then read
+ * `var(--evo-group-name)` in its rules.
+ * Regenerate with: node packages/scripts/gen-client-tokens.mjs packages
+ * @module @deepseek-ai/dsh-evolution-client-scale
+ */
+/** Every custom property of the scale, in the source order. */
+export declare const TOKENS: Readonly<Record<string, string>>;
+/** The declarations, without a selector. */
+export declare const TOKEN_CSS: string;
+/**
+ * The scale, declared on one element so it never leaks into the host shell.
+ * @param scope - the selector the custom properties are declared on.
+ * @returns the declaration block to put in the stylesheet.
+ */
+export declare function tokenVars(scope: string): string;
+//# sourceMappingURL=tokens.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-skill-history",
   "description": "Web surface for skill content history: loopback host routes plus the sidebar panel (community build)",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "publishConfig": {
     "access": "public"
   },
@@ -30,23 +30,23 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@lmzhen/dsh-evolution-core": "^0.14.0"
+    "@lmzhen/dsh-evolution-core": "^0.15.0"
   },
   "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.14.0"
+    "@lmzhen/dsh-evolution-curator": "^0.15.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-host-webserver": "^0.1.5-rc.2",
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
-    "@lmzhen/dsh-evolution-core": "^0.14.0",
-    "@lmzhen/dsh-evolution-curator": "^0.14.0",
-    "@lmzhen/dsh-evolution-io": "^0.14.0",
-    "@lmzhen/dsh-evolution-io-node": "^0.14.0"
+    "@lmzhen/dsh-evolution-core": "^0.15.0",
+    "@lmzhen/dsh-evolution-curator": "^0.15.0",
+    "@lmzhen/dsh-evolution-io": "^0.15.0",
+    "@lmzhen/dsh-evolution-io-node": "^0.15.0"
   },
   "dsh": {
     "client": {