@nanmicoder/dsh-skills-hub 0.0.1 → 0.0.2

package/lib/skills/management.js

@@ -1,10 +1,31 @@
-/** Local management only addresses entries freshly discovered inside configured user roots. */
+/**
+ * Local skill management: one discovered entry at a time.
+ *
+ * Every function here starts from a key, never from a client-supplied path: the
+ * roots are re-scanned on each call, and only an entry that scan just produced
+ * can be read or removed. A path that arrives from the browser is therefore
+ * always interpreted *inside* an entry this process has already vouched for.
+ *
+ * The detail read is what the panel's local skill page renders: the SKILL.md
+ * document, its raw frontmatter block and a bounded inventory of the skill's own
+ * files. Nothing here consults a market provider — an installed skill stays
+ * readable with the network down.
+ */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { readBoundedText } from "./read-text.js";
 import { randomUUID } from 'node:crypto';
 import { MarketInstallError } from "../market/install-service.js";
+import { detectMarketLanguage } from "../market/types.js";
 import { scanInstalledSkills } from "./installed.js";
+import { readBoundedText } from "./read-text.js";
+/** Largest SKILL.md the local detail endpoint returns, matching the market preview policy. */
+const MAX_DOCUMENT_BYTES = 2 * 1024 * 1024;
+/** Largest single document the browser may pull into the file viewer. */
+const MAX_PREVIEW_BYTES = 300 * 1024;
+/** Frontmatter kept for the metadata panel; a pathological header cannot fill it. */
+const MAX_FRONTMATTER_BYTES = 16 * 1024;
+/** Entries listed for one skill before the walk stops. */
+const MAX_LISTED_FILES = 500;
 async function resolveEntry(roots, key) {
     if (!/^[a-f0-9]{64}$/.test(key))
         throw new MarketInstallError(400, 'BAD_REQUEST', 'Invalid installed skill key');
@@ -13,15 +34,172 @@ async function resolveEntry(roots, key) {
         throw new MarketInstallError(404, 'MARKET_NOT_INSTALLED', 'Installed skill no longer exists');
     return entry;
 }
+/**
+ * Raw frontmatter block, kept as YAML text.
+ *
+ * Parsing it into structure would mean shipping a YAML reader for a panel that
+ * only needs to *show* the header, and the market detail's structured panel is
+ * fed by upstream JSON this plugin does not have for a hand-written skill. The
+ * verbatim block is also what the file actually contains, so nothing is lost.
+ */
+export function extractFrontmatter(markdown) {
+    const text = markdown.startsWith('\uFEFF') ? markdown.slice(1) : markdown;
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---')
+        return null;
+    for (let index = 1; index < lines.length; index++) {
+        const marker = (lines[index] ?? '').trim();
+        if (marker !== '---' && marker !== '...')
+            continue;
+        const block = lines.slice(1, index).join('\n').trim();
+        return block === '' ? null : block.slice(0, MAX_FRONTMATTER_BYTES);
+    }
+    // Unterminated header: the document is ordinary Markdown, as the browser's
+    // strip helper already assumes.
+    return null;
+}
+/**
+ * Inventory one entry's own files.
+ *
+ * The walk never leaves the entry: directories are descended, symlinked entries
+ * are listed as nothing at all, and the provenance sidecar (a dot-file, like
+ * every other dot-entry) is skipped because it is plugin bookkeeping rather than
+ * installed payload. A flat skill is a single file and reports itself.
+ */
+export async function listEntryFiles(item) {
+    const stats = await fs.stat(item.dirPath);
+    if (!stats.isDirectory()) {
+        return [{ path: path.basename(item.dirPath), size: stats.size, language: detectMarketLanguage(item.dirPath) }];
+    }
+    const files = [];
+    const pending = [''];
+    while (pending.length > 0 && files.length < MAX_LISTED_FILES) {
+        const relativeDir = pending.pop();
+        if (relativeDir === undefined)
+            break;
+        const absoluteDir = relativeDir === '' ? item.dirPath : path.join(item.dirPath, relativeDir);
+        let entries;
+        try {
+            entries = await fs.readdir(absoluteDir, { withFileTypes: true });
+        }
+        catch {
+            // Raced with a concurrent removal — list what is still there.
+            continue;
+        }
+        entries.sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            if (files.length >= MAX_LISTED_FILES)
+                break;
+            if (entry.name.startsWith('.'))
+                continue;
+            const relative = relativeDir === '' ? entry.name : `${relativeDir}/${entry.name}`;
+            if (entry.isDirectory()) {
+                pending.push(relative);
+                continue;
+            }
+            // `isFile()` excludes symlinks: a linked file is not part of the payload.
+            if (!entry.isFile())
+                continue;
+            try {
+                const fileStats = await fs.lstat(path.join(absoluteDir, entry.name));
+                if (!fileStats.isFile())
+                    continue;
+                files.push({ path: relative, size: fileStats.size, language: detectMarketLanguage(entry.name) });
+            }
+            catch {
+                // Raced with a concurrent removal.
+            }
+        }
+    }
+    files.sort((left, right) => left.path.localeCompare(right.path));
+    return files;
+}
+/**
+ * Validate one browser-supplied relative path.
+ *
+ * Absolute paths, `..` segments, empty segments and NUL are rejected outright;
+ * the caller then proves containment against the entry's real path, so a
+ * traversal cannot be smuggled in through either spelling or a symlink.
+ */
+function requireRelativePath(value) {
+    const normalized = value.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (normalized === '' || normalized.includes('\0') || path.isAbsolute(normalized)) {
+        throw new MarketInstallError(400, 'BAD_REQUEST', 'Invalid skill file path');
+    }
+    const segments = normalized.split('/');
+    if (segments.some(segment => segment === '' || segment === '.' || segment === '..')) {
+        throw new MarketInstallError(400, 'BAD_REQUEST', 'Invalid skill file path');
+    }
+    return segments.join('/');
+}
+/** Whether `candidate` is `root` itself or sits underneath it. */
+function contains(root, candidate) {
+    return candidate === root || candidate.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`);
+}
+/** Read the SKILL.md document plus the entry inventory the local detail page renders. */
 export async function readInstalledSkill(roots, key) {
     const item = await resolveEntry(roots, key);
     const stats = await fs.stat(item.dirPath);
     const file = stats.isDirectory() ? path.join(item.dirPath, 'SKILL.md') : item.dirPath;
-    const content = await readBoundedText(file, 2 * 1024 * 1024);
+    const content = await readBoundedText(file, MAX_DOCUMENT_BYTES);
     if (content.truncated) {
         throw new MarketInstallError(413, 'FILE_TOO_LARGE', 'Skill preview exceeds 2 MB');
     }
-    return { item, markdown: content.text };
+    return {
+        item,
+        markdown: content.text,
+        frontmatter: extractFrontmatter(content.text),
+        files: await listEntryFiles(item),
+    };
+}
+/**
+ * Read one file of one entry.
+ *
+ * A flat skill exposes exactly itself — never its siblings in the same root —
+ * and a directory bundle exposes only what resolves back inside its own real
+ * path, so a symlink planted in the tree cannot turn this endpoint into an
+ * arbitrary-file reader.
+ */
+export async function readInstalledFile(roots, key, requested) {
+    const item = await resolveEntry(roots, key);
+    const relative = requireRelativePath(requested);
+    const stats = await fs.stat(item.dirPath);
+    let documentPath;
+    if (stats.isDirectory()) {
+        const base = await fs.realpath(item.dirPath);
+        const candidate = path.resolve(base, relative);
+        if (!contains(base, candidate))
+            throw new MarketInstallError(400, 'BAD_REQUEST', 'Invalid skill file path');
+        let resolved;
+        try {
+            resolved = await fs.realpath(candidate);
+        }
+        catch {
+            throw new MarketInstallError(404, 'MARKET_NOT_INSTALLED', 'Skill file no longer exists');
+        }
+        if (!contains(base, resolved)) {
+            throw new MarketInstallError(400, 'BAD_REQUEST', 'Skill file escapes its directory');
+        }
+        documentPath = resolved;
+    }
+    else {
+        if (relative !== path.basename(item.dirPath)) {
+            throw new MarketInstallError(400, 'BAD_REQUEST', 'Invalid skill file path');
+        }
+        documentPath = await fs.realpath(item.dirPath);
+    }
+    const documentStats = await fs.stat(documentPath);
+    if (!documentStats.isFile())
+        throw new MarketInstallError(400, 'BAD_REQUEST', 'Skill file is not a document');
+    const content = await readBoundedText(documentPath, MAX_PREVIEW_BYTES);
+    return {
+        path: relative,
+        content: content.text,
+        language: detectMarketLanguage(relative),
+        size: documentStats.size,
+        // Truncation is not an error: the browser labels the partial document.
+        truncated: content.truncated,
+    };
 }
 /** Rename the selected entry out of discovery before deletion. Symlink targets are never removed. */
 export async function removeInstalledSkill(roots, key, allowUninstall) {

package/lib/skills/root.js

@@ -49,7 +49,7 @@ function expandHomePath(value) {
  * blank `$DSH_HOME` is treated as unset so a stray empty variable can never
  * resolve the harness home to the current working directory.
  */
-function resolveDshHome(configured) {
+export function resolveDshHome(configured) {
     if (typeof configured === 'string' && configured.trim() !== '') {
         return path.resolve(expandHomePath(configured.trim()));
     }

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

@@ -68,9 +68,13 @@ export declare class SkillsHubApiError extends Error {
  */
 export declare function isAbortError(error: unknown): boolean;
 /** Search the catalogue (market sources) — the remote list page. */
-export declare function fetchMarketList(query: MarketQuery, signal?: AbortSignal): Promise<MarketListResult>;
+export declare function fetchMarketList(query: MarketQuery, signal?: AbortSignal, options?: {
+    refresh?: boolean;
+}): Promise<MarketListResult>;
 /** One skill's full detail plus the health of the source that served it. */
-export declare function fetchSkillDetail(id: string, signal?: AbortSignal): Promise<{
+export declare function fetchSkillDetail(id: string, signal?: AbortSignal, options?: {
+    refresh?: boolean;
+}): Promise<{
     skill: NormalizedSkillDetail;
     sourceStatus: SourceStatusInfo;
 }>;
@@ -94,11 +98,35 @@ export declare function uninstallSkill(id: string): Promise<{
     removedPath: string;
     skill: NormalizedSkill;
 }>;
-/** Preview the exact local copy without consulting a market provider. */
-export declare function fetchInstalledDetail(key: string, signal?: AbortSignal): Promise<{
+/**
+ * One file of an installed skill, as the file tab lists it.
+ *
+ * `language` is the Host's mapping from the file extension and `size` is the
+ * real size on disk, so a truncated preview still reports the document it came
+ * from rather than the bytes that fit through the endpoint.
+ */
+export interface InstalledFileEntry {
+    path: string;
+    size: number;
+    language: string;
+}
+/**
+ * The local skill page's payload.
+ *
+ * `markdown` is the whole SKILL.md (frontmatter included) and `frontmatter` is
+ * that same header as YAML text: the market detail's structured metadata panel
+ * is fed by upstream JSON, and a hand-written skill has no such record.
+ */
+export interface InstalledSkillDetail {
     item: InstalledSkillRecord;
     markdown: string;
-}>;
+    frontmatter: string | null;
+    files: InstalledFileEntry[];
+}
+/** Preview the exact local copy without consulting a market provider. */
+export declare function fetchInstalledDetail(key: string, signal?: AbortSignal): Promise<InstalledSkillDetail>;
+/** One file of an installed skill; the Host validates the key and contains the path. */
+export declare function fetchInstalledFile(key: string, path: string, signal?: AbortSignal): Promise<MarketFileContent>;
 /** Remove a specifically selected local entry after the management UI confirmation. */
 export declare function removeInstalled(key: string): Promise<{
     item: InstalledSkillRecord;

package/lib/types/client/components/InstallConfirmDialog.d.ts

@@ -7,6 +7,12 @@ export interface InstallConfirmSkill {
     version?: string;
     securityStatus: SecurityStatus;
     authorName: string;
+    /**
+     * When the catalogue data behind this dialog was read from upstream, if it
+     * came from a snapshot. Installing is a trust decision, so the confirmation
+     * cannot present a cached security verdict as a fresh one.
+     */
+    snapshotAt?: number;
 }
 /**
  * Install confirmation.

package/lib/types/client/components/InstalledSkillDetail.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Installed skill detail page.
+ *
+ * The list's "view" affordance used to open a 380px confirmation-style modal,
+ * which is the wrong container for a document: SKILL.md is a page of prose with
+ * tables and code, and the marketplace already answers the same question with a
+ * full-panel page. This page is that same reading surface (`SkillDetailShell`),
+ * fed by the filesystem instead of a provider.
+ *
+ * What it deliberately does *not* do is pretend a local skill is a market
+ * entry. There is no author, download count or security report to show, so
+ * those rows are absent rather than zero. Where the two identities do meet —
+ * a skill installed from a market, proven by its `.skills-hub.json` sidecar —
+ * the page links to the market detail instead of duplicating it, which keeps
+ * upstream data upstream and this page readable with the network down.
+ */
+import { type InstalledSkillRecord } from '../api.ts';
+export declare function InstalledSkillDetail(props: {
+    item: InstalledSkillRecord;
+    onBack: () => void;
+    onUninstall: (item: InstalledSkillRecord) => void;
+    /** Open the same skill's market page; only offered for market provenance. */
+    onOpenMarket: (id: string) => void;
+}): JSX.Element;

package/lib/types/client/components/InstalledSkills.d.ts

@@ -1,3 +1,20 @@
-export declare function InstalledSkills({ onChanged }: {
+/**
+ * Installed skills: the local inventory and its reading page.
+ *
+ * Two views, one component. The detail page replaces the list *inside* this
+ * component rather than in `MarketPage`, so the list is never unmounted: the
+ * search query, the loaded rows and the scroll position are all still there when
+ * the reader comes back. That is also why the selected row is stored as a key
+ * and resolved against the current rows — a refresh that drops the entry closes
+ * the page instead of leaving it pointing at something that no longer exists.
+ *
+ * Removal stays a confirmation modal on purpose: it is a short yes/no about a
+ * destructive action, which is exactly what the primitive's dialog is for. The
+ * skill's *content* is not, which is why it moved to a page.
+ */
+export declare function InstalledSkills(props: {
+    /** A removal changed the local inventory; the market half refreshes too. */
     onChanged: () => void;
+    /** Open the market page of a skill that came from a market. */
+    onOpenMarket: (id: string) => void;
 }): JSX.Element;

package/lib/types/client/components/MarkdownView.d.ts

@@ -1,4 +1,10 @@
-/** Self-contained GFM rendering for untrusted marketplace and local skill docs. */
+/**
+ * Self-contained GFM rendering for untrusted marketplace and local skill docs.
+ *
+ * Raw HTML is skipped and external links are opened with `noopener noreferrer`;
+ * the typography lives in the detail shell so a rendered document looks the same
+ * in the overview tab and in the file viewer.
+ */
 export declare function MarkdownView({ content }: {
     content: string;
 }): JSX.Element;

package/lib/types/client/components/SkillAvatar.d.ts

@@ -8,7 +8,7 @@ import type { MarketSource } from '../../market/types.ts';
  */
 export declare function SkillAvatar(props: {
     name: string;
-    source: MarketSource;
+    source: MarketSource | 'local';
     iconUrl?: string;
     size: number;
 }): JSX.Element;

package/lib/types/client/components/SkillDetailShell.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The detail surface shared by the market catalogue and the installed inventory.
+ *
+ * Both pages answer the same question — "what is inside this skill?" — and the
+ * only real difference is where the facts come from: an upstream provider or the
+ * filesystem. Everything that is *reading* rather than *fetching* therefore
+ * lives here: the back affordance, the identity header, the two tabs, the
+ * document column, the facts rail and the focus move that keeps a keyboard user
+ * from being left at the top of the document when the list is replaced.
+ *
+ * The two pages are not identical, so the shell takes slots rather than a data
+ * model: `badges`, `notice`, `overview`, `files` and `rail` are composed by the
+ * caller, while each caller owns its own loading state and its own choice of tab
+ * storage (the market page keeps it in `MarketState`, the local page in its own
+ * component state).
+ */
+import { type ReactNode } from 'react';
+/** Tab values every detail page offers, in render order. */
+export type SkillDetailTab = 'overview' | 'files';
+/**
+ * The shell's stylesheet, re-exported for its callers.
+ *
+ * The pages built on this shell also render shell-shaped fragments (a report
+ * row, a path line, a facts list) and reaching them through an import is more
+ * honest than re-declaring near-copies of the same rules in a second module.
+ */
+export declare const detailStyles: Record<string, string>;
+/** One label/value row of the facts rail. */
+export declare function Fact(props: {
+    label: string;
+    children: ReactNode;
+}): JSX.Element;
+export declare function SkillDetailShell(props: {
+    /** Identity of the rendered subject; changing it moves focus back to the heading. */
+    focusKey: string;
+    onBack: () => void;
+    backLabel: string;
+    avatar: ReactNode;
+    /** Small line above the name: source, version, provenance. */
+    eyebrow: ReactNode;
+    name: string;
+    badges?: ReactNode;
+    summary?: string;
+    /** Full-width band under the header (warnings, security reports). */
+    notice?: ReactNode;
+    overviewLabel: string;
+    filesLabel: string;
+    activeTab: SkillDetailTab;
+    onTabChange: (tab: SkillDetailTab) => void;
+    overview: ReactNode;
+    files: ReactNode;
+    rail: ReactNode;
+}): JSX.Element;
+/**
+ * Keeps the detail layout stable while its request is in flight.
+ *
+ * It renders the same boxes as the real page rather than a spinner, because the
+ * click that opens a detail is the moment the panel changes shape; a centered
+ * "loading" line would make that change happen twice.
+ */
+export declare function SkillDetailSkeleton({ onBack }: {
+    onBack: () => void;
+}): JSX.Element;

package/lib/types/client/components/SkillDetailView.d.ts

@@ -1,11 +1,13 @@
 import type { NormalizedSkillDetail } from '../../market/types.ts';
 import type { MarketController, MarketState } from '../state.ts';
 /**
- * Skill detail page.
+ * Market skill detail page.
  *
  * Like the home page this component owns no data: the tab, the selected file
  * and the file contents all live in `MarketState`, so switching tabs or
- * re-opening a skill does not lose its place.
+ * re-opening a skill does not lose its place. The reading surface itself — back
+ * affordance, header, tabs, facts rail — is `SkillDetailShell`, which the local
+ * installed page uses too.
  *
  * The bundled GFM renderer handles catalogue Markdown without relying on a
  * host renderer delegate. Raw HTML is disabled and URLs use its safe default.
@@ -15,7 +17,3 @@ export declare function SkillDetailView(props: {
     state: MarketState;
     controller: MarketController;
 }): JSX.Element;
-/** Keeps the detail layout stable while its network request is in flight. */
-export declare function SkillDetailSkeleton({ onBack }: {
-    onBack: () => void;
-}): JSX.Element;

package/lib/types/client/components/SkillFiles.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Files tab body, shared by the two detail pages.
+ *
+ * The market page lists provider file metadata and the local page lists the
+ * bytes on disk, but both are the same control: a picker on the left, one
+ * document on the right, and a copy button that confirms itself. The only
+ * difference the caller keeps is how a selection is fetched.
+ *
+ * A markdown document opens *rendered*: SKILL.md is prose meant to be read, and
+ * showing its source first answers a question nobody asked. Installing still has
+ * to be a trust decision, though, so the raw bytes are one toggle away — with
+ * line numbers and the copy button pointed at exactly what is on disk. Other
+ * files have no rendered form and stay source-only.
+ */
+import type { MarketFileContent } from '../../market/types.ts';
+/** The subset of a file row this control renders; both pages' metadata fits it. */
+export interface SkillFileListItem {
+    path: string;
+    size: number;
+    language: string;
+    /** Provider flagged the file as beyond the preview/install limit. */
+    tooBig?: boolean;
+}
+export declare function SkillFiles(props: {
+    files: SkillFileListItem[];
+    /** Already-fetched document for the selected path, or `null` while none is loaded. */
+    selected: MarketFileContent | null;
+    loading: boolean;
+    /** Reader-facing failure of the last selection, if any. */
+    error?: string | null;
+    onSelect: (path: string) => void;
+}): JSX.Element;

package/lib/types/client/components/SourceStatusBar.d.ts

@@ -5,6 +5,10 @@ import type { MarketSource, SourceStatusInfo } from '../../market/types.ts';
  * The upstream error string rides the pill's `title` instead of being printed:
  * a 720px panel has no room for a stack trace next to two source names, and an
  * operator who needs it can hover.
+ *
+ * The snapshot age *is* printed: a healthy source can still be answering from a
+ * cache, and a reader deciding whether to install third-party code is entitled
+ * to see that the page in front of them was read minutes ago rather than now.
  */
 export declare function SourceStatusBar(props: {
     sources: Record<MarketSource, SourceStatusInfo>;

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

@@ -69,3 +69,7 @@ export declare function ChevronRightIcon({ size, className }: SkillsHubIconProps
 export declare function CloseIcon({ size, className }: SkillsHubIconProps): JSX.Element;
 /** Price tag: leading glyph of a card's tag row. */
 export declare function TagIcon({ size, className }: SkillsHubIconProps): JSX.Element;
+/** Folder: leading glyph of the installed skill's location line. */
+export declare function FolderIcon({ size, className }: SkillsHubIconProps): JSX.Element;
+/** Arrow leaving a frame: open the same skill in the marketplace. */
+export declare function ExternalLinkIcon({ size, className }: SkillsHubIconProps): JSX.Element;

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

@@ -29,6 +29,34 @@ declare const zhDictionary: {
     localUninstallDescription: string;
     unlinkDescription: string;
     uninstalling: string;
+    uninstallDisabled: string;
+    copyPath: string;
+    copiedPath: string;
+    sourceLabel: string;
+    managedByHub: string;
+    unmanagedSkill: string;
+    symlinkSkill: string;
+    installedAtLabel: string;
+    skillKind: string;
+    bundleSkill: string;
+    flatSkill: string;
+    filesCount: string;
+    emptyDocument: string;
+    installedReadFailed: string;
+    openInMarket: string;
+    fileView: string;
+    filePreview: string;
+    fileSource: string;
+    snapshotAge: string;
+    ageJustNow: string;
+    ageMinutes: string;
+    ageHours: string;
+    ageDays: string;
+    refreshNow: string;
+    refreshSnapshot: string;
+    detailSnapshot: string;
+    installSnapshot: string;
+    marketProvenance: string;
     panel: string;
     title: string;
     subtitle: string;
@@ -37,6 +65,7 @@ declare const zhDictionary: {
     'source.all': string;
     'source.clawhub': string;
     'source.skillhub': string;
+    'source.local': string;
     'security.all': string;
     'security.verified': string;
     'security.benign': string;
@@ -96,6 +125,7 @@ declare const zhDictionary: {
     uninstallDone: string;
     noFiles: string;
     fileTooLarge: string;
+    fileTruncated: string;
     copy: string;
     copied: string;
     unoaudited: string;

package/lib/types/client/relative-time.d.ts

@@ -0,0 +1,13 @@
+/**
+ * How old a snapshot is, in the panel's own vocabulary.
+ *
+ * The panel shows cached catalogue data, so "when was this actually fetched" is
+ * part of the answer rather than a debug detail: a reader who is about to
+ * install third-party code is entitled to know whether the security report in
+ * front of them was read a minute ago or yesterday.
+ */
+import type { Translate } from './locale-context.tsx';
+/** Coarse buckets: the first match wins, and precision beyond them is noise. */
+export declare function formatAge(t: Translate, from: number, now?: number): string;
+/** Absolute timestamp for the hover text, so the bucket never hides the fact. */
+export declare function formatStamp(from: number): string;

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

@@ -1,2 +1,41 @@
+/**
+ * Frontmatter handling for skill documents.
+ *
+ * A `SKILL.md` opens with a YAML block, and feeding that block to a markdown
+ * renderer is not merely ugly — it is wrong: a lone `---` is a setext underline,
+ * so the closing fence promotes the whole metadata block into one giant heading.
+ * The block is split off here instead, so the UI can render it as structured
+ * metadata (`FrontmatterPanel`) while the rest of the document goes to the
+ * renderer. The approach mirrors the desktop project's `skillFrontmatter.ts`.
+ *
+ * The parser is a deliberately small YAML subset — scalars, inline and block
+ * sequences, `|`/`>` block scalars, and one level of nested mapping that is kept
+ * as the raw YAML it is — because skill frontmatter is flat by convention and a
+ * full YAML engine is a dependency this browser bundle does not need. It never
+ * throws: a document without a fence, or with an unterminated one, comes back as
+ * body only.
+ */
+/** One document separated into its metadata and everything else. */
+export interface SkillFrontmatterSplit {
+    /** Parsed metadata, or `null` when the document carries none worth showing. */
+    frontmatter: Record<string, unknown> | null;
+    /** The document with its metadata block removed. */
+    body: string;
+}
+/**
+ * Parse a metadata block that has already been extracted — the Host bounds its
+ * size before it reaches the browser, so this entry point works on that text.
+ *
+ * @param yaml - the block's text, without its fences.
+ * @returns the parsed keys, or `null` when the block carries nothing to show.
+ */
+export declare function parseSkillFrontmatter(yaml: string): Record<string, unknown> | null;
+/**
+ * Separate a document's frontmatter from its body.
+ *
+ * @param markdown - the whole document.
+ * @returns the parsed metadata (or `null`) plus the body to render.
+ */
+export declare function splitSkillFrontmatter(markdown: string): SkillFrontmatterSplit;
 /** Frontmatter is metadata, not part of the skill's rendered instructions. */
 export declare function stripSkillFrontmatter(markdown: string): string;

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

@@ -13,8 +13,8 @@
  *    already holds.
  *  - **in-flight guards**: one install/uninstall per id, one page per cursor, one
  *    detail/file request per target.
- *  - **detail/file caching**: reopening a skill is instant and cannot blank the
- *    pane with a spinner.
+ *  - **detail snapshots**: reopening can show the previous copy immediately,
+ *    while the Host rechecks its TTL and current install annotations.
  *  - **local management**: the InstalledSkills component independently lists what is already
  *    on disk (`fetchInstalled`) instead of asking the market, matching the
  *    contract's §5.3 behaviour.
@@ -49,6 +49,8 @@ export interface MarketState {
     items: NormalizedSkill[];
     nextCursor: string | null;
     sources: Record<MarketSource, SourceStatusInfo>;
+    /** Each card retains the provenance of its own page when more pages append. */
+    itemStatuses: Record<string, SourceStatusInfo>;
     loading: boolean;
     loadingMore: boolean;
     error: string | null;
@@ -59,6 +61,8 @@ export interface MarketState {
         id: string;
     };
     detail: NormalizedSkillDetail | null;
+    /** Provenance of `detail`: when it was fetched upstream, and whether it is a snapshot. */
+    detailStatus: SourceStatusInfo | null;
     detailLoading: boolean;
     detailError: string | null;
     activeTab: 'overview' | 'files';
@@ -73,13 +77,18 @@ export interface MarketState {
 export interface MarketController {
     state: MarketState;
     readonly injected: MarketPageInjected;
-    refresh(): Promise<void>;
+    /** `force` is the reader's refresh: it must not be answered from the cache. */
+    refresh(options?: {
+        force?: boolean;
+    }): Promise<void>;
     loadMore(): Promise<void>;
     setQuery(q: string): void;
     setSource(source: MarketFilters['source']): void;
     setSecurity(security: MarketFilters['security']): void;
     setInstalledFilter(installed: MarketFilters['installed']): void;
-    openDetail(id: string): Promise<void>;
+    openDetail(id: string, options?: {
+        refresh?: boolean;
+    }): Promise<void>;
     closeDetail(): void;
     setTab(tab: 'overview' | 'files'): void;
     selectFile(path: string): Promise<void>;