feat(plugin-detail): show Markdown plugin details on bundle and market entry pages

Plugins bundle pages and Discover entry pages show the plugin's long
description first, as Markdown with images, in a height-limited region
without its own heading. The document is the file locale meta.detail
names, otherwise the package README, otherwise (market entries only)
the declared repository's README.

The new dsh-plugin-detail library selects documents and reads local
package directories and npm file CDNs without state. plugin-manager
reads installed and offered bundles through readBundleDetail; plugin-market
reads market entries through readEntryDetail, single-file APIs, and a
size-limited partial clone cache serialized across processes. Raw HTML is
omitted, relative links stay text, and relative images load from Host
routes with a sandbox CSP.
This commit is contained in:
turtle1999 committed 2026-10-19 19:13:22 +08:00
1 parent 82a5ae1744
commit 9c8522bb64
111 files changed
+5057 -141

No files matched your search

@@ -0,0 +1,58 @@
/** A bundle's long description on its page: the Markdown document the Host reads for it. */
import { useEffect, useMemo, type ReactNode } from 'react'
import { DetailDocument, detailDocumentState, useDetailDocumentLabels, type MarkdownPathImages } from '@deepseek-ai/dsh-client-ui-primitives'
import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
import { bundleDetailKey, type BundleDetailFailure, type BundleDetailsState } from './detail-store.ts'
type Translate = PropsLocale<'pluginManager'>['t']
const FAILURE_KEYS = {
'too-large': 'detailTooLarge',
'network': 'detailNetwork',
'denied': 'detailFailed',
'git-unavailable': 'detailFailed',
'invalid': 'detailInvalid',
'other': 'detailFailed',
} as const satisfies Record<BundleDetailFailure, string>
/** What the section reads and calls; the page passes them from its injected face. */
export interface BundleDetailSectionProps {
readonly name: string
readonly version: string | undefined
/** Whether the bundle's files are unavailable, so the Host reads its offered version from the npm file CDNs. */
readonly fromNpm: boolean
readonly language: string
readonly details: BundleDetailsState
readonly t: Translate
readonly load: (name: string, version: string | undefined, language: string, fromNpm: boolean) => void
readonly retry: (name: string, version: string | undefined, language: string, fromNpm: boolean) => void
readonly image: (name: string, document: string, destination: string, fromNpm: boolean) => string | undefined
}
/**
* Read and render a bundle's detail document in the active language; relative images load from the Host beside it.
* @param props - the bundle, the language, the reads, and the page's callbacks.
* @returns the section, or null when the bundle has no document.
*/
export function BundleDetailSection(props: BundleDetailSectionProps): ReactNode {
const { name, version, fromNpm, language, details, t, load, retry, image } = props
const key = bundleDetailKey(name, version, language)
const state = details[key]
// The key names the read completely; a read the controller forgot, after a profile change, starts again.
const missing = state === undefined
useEffect(() => { if (missing) load(name, version, language, fromNpm) }, [key, missing])
const labels = useDetailDocumentLabels({
title: t('detailTitle'), loading: t('detailLoading'), retry: t('retry'), copy: t('copy'), copied: t('copied'),
codeBlock: t('codeBlock.title'), wrap: t('codeBlock.wrap'), unwrap: t('codeBlock.unwrap'), footnotes: t('detailFootnotes'),
})
const detail = state?.status === 'ready' ? state.detail : undefined
const document = detail?.status === 'found' ? detail.path : undefined
const images = useMemo<MarkdownPathImages | undefined>(
() => document === undefined ? undefined : { resolve: value => image(name, document, value, fromNpm) },
[name, document, fromNpm, image],
)
const shown = detailDocumentState(state?.status === 'error'
? { status: 'error', message: t(FAILURE_KEYS[state.failure]) }
: state === undefined || state.status === 'loading' ? state : { status: 'ready', markdown: detail?.status === 'found' ? detail.markdown : undefined })
return <DetailDocument state={shown} labels={labels} images={images} onRetry={() => { retry(name, version, language, fromNpm) }} />
}
@@ -33,6 +33,7 @@ import { managementText, noticeText, packageText, registryText, restartText, row
import type { PluginPackageRef, PluginRowRef, PluginsSubject } from './slot-contract.ts'
import type { ConfigPageForm } from './slot-contract.ts'
import { UpdateDialog, VersionSection } from './versions.tsx'
import { BundleDetailSection } from './BundleDetailSection.tsx'
import css from './PluginManagerPage.module.css'
import badgeSkillPreview from './assets/badge-skill-preview.svg'
import badgeSkillPreviewZh from './assets/badge-skill-preview.zh.svg'
@@ -716,12 +717,14 @@ function RowDetail({ pkg, row, t, resolveText, onBack, renderSlot, form }: {
* and configure controls; and where it comes from.
*/
function PackageDetail({
pkg, t, resolveText, busy, rowBusy, configured, configure, renderSlot, inMore, versions,
pkg, t, resolveText, busy, rowBusy, configured, configure, renderSlot, inMore, versions, detail,
onBack, onSetEnabled, onUninstall, onUpdate, onSetRowEnabled, onEnsureVersions, onCheckVersions, onUpdateVersion,
}: {
readonly pkg: PackageView
/** The package's version check, when one started. */
readonly versions: VersionCheck | undefined
/** The bundle's detail document section, shown first among the page's sections. */
readonly detail: ReactNode
readonly t: Translate
readonly resolveText: ResolveText
readonly busy: boolean
@@ -808,6 +811,7 @@ function PackageDetail({
{pkg.readOnlyReason === undefined ? null : <p className={css.reason} role="status">{managementText({ code: pkg.readOnlyReason }, t)}</p>}
{preview === undefined ? null : <PackagePreview src={preview} title={title} t={t} />}
<div className={css.detailSections}>
{detail}
{configured
? (
<section className={css.detailSection} data-plugin-config>
@@ -1547,6 +1551,8 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode {
// What is open; a package that leaves the list (uninstalled) drops back to the cards.
const view = props.useStore(state => state.view), { setView, setTab } = props.actions
const tabs = props.usePluginTabs(snapshot => snapshot)
const bundleDetails = props.useBundleDetails(snapshot => snapshot)
const language = props.useLocale(snapshot => snapshot.active)
const selectedTab = props.useStore(state => state.tab)
// A contributed tab that left the ledger falls back to Installed, and stays there when it returns.
const tab = tabs.some(item => item.id === selectedTab) ? selectedTab : INSTALLED_TAB
@@ -1769,6 +1775,11 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode {
configure={configure(openPkg)}
renderSlot={renderSlot}
inMore={openPkgInMore}
detail={(
<BundleDetailSection name={openPkg.name} version={openPkg.version} fromNpm={openPkg.availability === 'missing'}
language={language} details={bundleDetails} t={t}
load={props.loadDetail} retry={props.retryDetail} image={props.detailImage} />
)}
onBack={() => { setView({ kind: openPkgInMore ? 'more' : 'list' }) }}
onSetEnabled={(enabled) => { props.setEnabled(openPkg.name, enabled) }}
onUninstall={() => { props.uninstall(openPkg.name) }}
@@ -0,0 +1,124 @@
/** Bundle detail reads: the long description of each bundle the page opens, read from the Host by name and language. */
import type { Context as ClientContext } from '@deepseek-ai/cordis'
import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-store'
import type { BundleDetail, RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
import { NPMMIRROR_REGISTRY } from '@deepseek-ai/dsh-plugin-manager/registry'
/** Why a bundle detail read failed: the Host's `plugin-manager/detail-unavailable` reason, or `other`. */
export type BundleDetailFailure = 'too-large' | 'network' | 'denied' | 'git-unavailable' | 'invalid' | 'other'
/** One bundle detail read. */
export type BundleDetailState =
| { readonly status: 'loading' }
| { readonly status: 'ready'; readonly detail: BundleDetail }
| { readonly status: 'error'; readonly failure: BundleDetailFailure }
/** Bundle detail reads by {@link bundleDetailKey}. */
export type BundleDetailsState = Readonly<Record<string, BundleDetailState>>
/**
* The identity of a bundle detail read: the bundle, its installed version, and the display language.
* @param name - the bundle's package name.
* @param version - the installed or offered version, so an updated bundle reads again.
* @param language - the display language.
* @returns the key of the read in {@link BundleDetailsState}.
*/
export function bundleDetailKey(name: string, version: string | undefined, language: string): string {
return JSON.stringify([name, version ?? null, language])
}
/** The Host route of images beside bundle detail documents, relative to the application base. */
const DETAIL_FILE_ROUTE = 'api/plugin-manager/detail-file'
function failureOf(failure: RemoteFailure): BundleDetailFailure {
return failure.code === 'plugin-manager/detail-unavailable' ? failure.details.reason : 'other'
}
/** Reads bundle detail documents and publishes them to the page. */
export class BundleDetailController {
/** Detail reads published to the page. */
readonly store: SnapshotStore<BundleDetailsState> = createSnapshotStore<BundleDetailsState>({})
/** The latest read of each key, numbered across the controller's lifetime; an older read's answer is dropped. */
private readonly reads = new Map<string, number>()
private sequence = 0
/** npm file CDNs to ask first, from the Host's latest registry comparison: npmmirror when its registry answered fastest. */
private npmFileSources: 'npmmirror'[] = []
private disposed = false
/**
* @param ctx - the page plugin's context, whose `remote.pluginManager` namespace answers.
* @param base - the application base URL that Host routes resolve against.
*/
constructor(private readonly ctx: ClientContext, private readonly base: () => string) {}
/**
* Read a bundle's document unless the read already ran or runs.
* @param name - the bundle's package name.
* @param version - its installed or offered version.
* @param language - the display language.
* @param fromNpm - whether the bundle's files are unavailable, so the Host reads its offered version from the npm file CDNs.
*/
load(name: string, version: string | undefined, language: string, fromNpm: boolean): void {
if (this.store.getSnapshot()[bundleDetailKey(name, version, language)] === undefined) void this.read(name, version, language, fromNpm)
}
/**
* Read a bundle's document again.
* @param name - the bundle's package name.
* @param version - its installed or offered version.
* @param language - the display language.
* @param fromNpm - whether the Host reads the bundle from the npm file CDNs.
*/
retry(name: string, version: string | undefined, language: string, fromNpm: boolean): void {
void this.read(name, version, language, fromNpm)
}
/**
* The URL of an image beside a bundle's document.
* @param name - the bundle's package name.
* @param document - the document's path inside the bundle.
* @param destination - the image destination as the document writes it.
* @param fromNpm - whether the Host reads the bundle from the npm file CDNs.
* @returns the authenticated Host URL, or undefined for an absolute, protocol-relative, or fragment destination.
*/
image(name: string, document: string, destination: string, fromNpm: boolean): string | undefined {
if (/^(?:[a-z][a-z\d+.-]*:|\/\/|#)/iu.test(destination)) return undefined
const sources = fromNpm ? this.npmFileSources : []
const query = new URLSearchParams({ bundle: name, document, path: destination, ...sources.length > 0 ? { sources: sources.join(',') } : {} })
return new URL(`${DETAIL_FILE_ROUTE}?${query.toString()}`, this.base()).href
}
/** Forget every read, so each shown bundle reads its document again; bundle files can change at any profile change. */
reset(): void {
this.reads.clear()
this.store.set({})
}
/** Stop publishing late settlements. */
dispose(): void {
this.disposed = true
}
private async read(name: string, version: string | undefined, language: string, fromNpm: boolean): Promise<void> {
const key = bundleDetailKey(name, version, language)
const read = ++this.sequence
this.reads.set(key, read)
this.publish(key, { status: 'loading' })
// The remote is captured before any wait: the plugin's context may be disposed while the comparison runs.
const { remote } = this.ctx
const current = (): boolean => !this.disposed && this.reads.get(key) === read
// Only a bundle read from the CDNs waits for the registry comparison.
if (fromNpm) {
const fastest = await remote.pluginRegistryProbe.fastest()
// A retry or reset started while the comparison ran settles the key instead.
if (!current()) return
this.npmFileSources = fastest.ok && fastest.value === NPMMIRROR_REGISTRY ? ['npmmirror'] : []
}
const answer = await remote.pluginManager.readBundleDetail(name, language, { npmFileSources: fromNpm ? this.npmFileSources : [] })
if (current()) this.publish(key, answer.ok ? { status: 'ready', detail: answer.value } : { status: 'error', failure: failureOf(answer.error) })
}
private publish(key: string, state: BundleDetailState): void {
this.store.set({ ...this.store.getSnapshot(), [key]: state })
}
}
@@ -84,6 +84,8 @@ export function apply(ctx: ClientContext): void {
ctx.effect(() => {
// A page never rendered holds no snapshot to refresh.
const refresh = (): void => {
// A profile change can replace a bundle's files, and a restarted Host is read afresh.
controller.details.reset()
if (controller.getSnapshot().status !== 'idle') void controller.load()
}
const disposers = [
@@ -286,6 +286,13 @@ export const zh = {
reasonIncompatibleInstall: '请安装与当前 DSH 兼容的插件版本。',
reasonIncompatibleInstalled: '请卸载后重新安装与当前 DSH 兼容的版本。',
reasonOperationError: 'Host 报告了一个错误',
detailTitle: '详细介绍',
detailLoading: '正在读取详细介绍',
detailTooLarge: '详细介绍超过大小限制,未加载',
detailNetwork: '无法连接到详细介绍的来源',
detailInvalid: '插件声明的详细介绍文件无效',
detailFailed: '无法读取详细介绍',
detailFootnotes: '脚注',
} satisfies Record<string, string>
/** Plugin manager locale key union. */
@@ -572,4 +579,11 @@ export const en = {
reasonIncompatibleInstall: 'Install a plugin version compatible with this DSH.',
reasonIncompatibleInstalled: 'Uninstall it and install a version compatible with this DSH.',
reasonOperationError: 'The Host reported an error.',
detailTitle: 'Details',
detailLoading: 'Reading details',
detailTooLarge: 'The details exceed the size limit and were not loaded.',
detailNetwork: 'Could not reach the source of the details.',
detailInvalid: 'The plugin declares an invalid details file.',
detailFailed: 'Could not read the details.',
detailFootnotes: 'Footnotes',
} satisfies Record<PluginManagerLocaleKey, string>
@@ -41,6 +41,8 @@ import type { ConfigLedger } from './config-ledger.ts'
import type { PluginTabInstall } from './slot-contract.ts'
import type { PluginTab } from './tab-ledger.ts'
import { shortName } from './presentation.ts'
import { BundleDetailController, type BundleDetailsState } from './detail-store.ts'
import type { LocaleSnapshot } from '@deepseek-ai/dsh-client-locale/client'
/** The action a failed notice names. */
export type FailedAction = 'enable' | 'disable' | 'uninstall' | 'rowEnable' | 'rowDisable'
@@ -389,7 +391,17 @@ export interface PluginManagerFace {
configLedger: HostObservable<ConfigLedger>
/** Tabs other plugins contribute, bound by the renderer as usePluginTabs. */
pluginTabs: HostObservable<readonly PluginTab[]>
/** Bundle detail reads, bound by the renderer as useBundleDetails. */
bundleDetails: SnapshotStore<BundleDetailsState>
/** The active locale, bound as useLocale, for the language detail documents are read in. */
locale: HostObservable<LocaleSnapshot>
}
/** Read a bundle's detail document unless the read already ran or runs. */
loadDetail: BundleDetailController['load']
/** Read a bundle's detail document again. */
retryDetail: BundleDetailController['retry']
/** The URL of an image beside a bundle's detail document, or undefined for a destination the page loads as written. */
detailImage: BundleDetailController['image']
/** Read the Host once the tab first renders. */
ensure: () => void
/** Read the Host again, then check every updatable package for newer versions. */
@@ -631,6 +643,8 @@ export class PluginManagerController {
private registryRead: RegistryRead | undefined
/** A Discover entry chose the dialog's registry; that choice applies to this dialog only and is never remembered. */
private transientRegistry = false
/** Bundle detail documents the page shows. */
readonly details: BundleDetailController
/** The registry last used from this browser, kept across dialogs and page loads; null until one was used. */
private readonly registryMemory: SnapshotStore<RegistryChoice | null> = createSnapshotStore<RegistryChoice | null>(null, {
persist: { name: 'dsh.plugin-manager.install-registry' },
@@ -642,6 +656,7 @@ export class PluginManagerController {
constructor(
private readonly ctx: ClientContext,
) {
this.details = new BundleDetailController(ctx, () => document.baseURI)
this.store = createSnapshotStore<PluginManagerState>({
status: 'idle', refreshStatus: 'idle', packages: [], busy: [], notice: null,
install: IDLE_INSTALL, confirm: null, highlight: null, versions: {}, update: null,
@@ -659,6 +674,7 @@ export class PluginManagerController {
/** Stop publishing and drop every late settlement. */
dispose(): void {
this.disposed = true
this.details.dispose()
this.registryRead = undefined
this.request = undefined
this.generation += 1
@@ -674,9 +690,16 @@ export class PluginManagerController {
inject(
configLedger: HostObservable<ConfigLedger>, pluginTabs: HostObservable<readonly PluginTab[]>, resolveText: PluginManagerFace['resolveText'],
): PluginManagerFace {
const details = this.details
return {
resolveText,
hooks: { pluginManager: this.store, configLedger, pluginTabs, configurations: this.ctx.configForms.describe() },
hooks: {
pluginManager: this.store, configLedger, pluginTabs, configurations: this.ctx.configForms.describe(),
bundleDetails: details.store, locale: this.ctx.locale,
},
loadDetail: (name, version, language, fromNpm) => { details.load(name, version, language, fromNpm) },
retryDetail: (name, version, language, fromNpm) => { details.retry(name, version, language, fromNpm) },
detailImage: (name, document, destination, fromNpm) => details.image(name, document, destination, fromNpm),
configForm: id => this.ctx.configForms.get(id),
ensure: () => { if (this.getSnapshot().status === 'idle') void this.load() },
refresh: () => { void this.refresh() },
@@ -160,7 +160,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
*/
'plugins.detail.badge': { kind: 'list'; scope: 'root'; owner: PluginDetailProps }
/**
* Sections under a detail page's own content: after the rows on a bundle's
* Sections under a detail page's own content: after the source on a bundle's
* page, after the configuration on a row's or an official plugin's page.
* An entry draws its own section chrome and renders null for a subject it
* has nothing for.