dsh-better-display 0.1.1

package/src/client/tool-activity.ts

@@ -0,0 +1,152 @@
+import type { AssistantBlock, ToolCallBlock, TurnLocation } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { ChatConversationViewNode } from '@deepseek-ai/dsh-client-ui-chat/client';
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { ReaderGroup } from './projection.js';
+
+export type ToolDraft = Extract<AssistantBlock, { kind: 'tool-call' }>;
+export type ToolPhase = 'preparing' | 'running' | 'returned' | 'succeeded' | 'failed' | 'interrupted';
+export type ToolCategory = 'write' | 'read' | 'terminal' | 'search' | 'web' | 'other';
+export interface ToolActivityEntry {
+  kind: 'tool'; key: string; callId: string; step: number; order: number;
+  draft?: ToolDraft; block?: ToolCallBlock;
+}
+export type ReaderFlowEntry = ToolActivityEntry | { kind: 'node'; key: string; nodeKey: string; order: number };
+
+/** Public Step data includes tool-only model output before a chat node exists. */
+export function readerFlow(group: ReaderGroup, turn: TurnLocation | undefined, get: (key: string) => ChatConversationViewNode | undefined): ReaderFlowEntry[] {
+  const flow: ReaderFlowEntry[] = [];
+  const calls = new Map<string, ToolActivityEntry>();
+  const assistantOrder = new Map<number, number>();
+  for (const key of group.keys) {
+    const node = get(key);
+    if (!node || node.visibility === 'hidden') continue;
+    const step = node.location.kind === 'step' ? node.location.step.step : 0;
+    if (node.kind === 'tool-call') {
+      const block = (node.data as { root: ToolCallBlock }).root;
+      calls.set(block.callId, { kind: 'tool', key: `reader-tool:${block.callId}`, callId: block.callId, step, block, order: node.anchorSeq });
+    } else {
+      flow.push({ kind: 'node', key, nodeKey: key, order: node.anchorSeq });
+      if (node.kind === 'assistant-step') assistantOrder.set(step, node.anchorSeq);
+    }
+  }
+  for (const step of turn?.steps ?? []) {
+    const data = step.data.get('assistant-step');
+    let index = 0;
+    for (const draft of data?.blocks ?? []) {
+      if (draft.kind !== 'tool-call' || !draft.callId) continue;
+      const previous = calls.get(draft.callId);
+      calls.set(draft.callId, previous ? { ...previous, draft } : {
+        kind: 'tool', key: `reader-tool:${draft.callId}`, callId: draft.callId, step: step.step, draft,
+        order: (assistantOrder.get(step.step) ?? step.start?.seq ?? 0) + .01 + index++ / 10000,
+      });
+    }
+  }
+  flow.push(...calls.values());
+  return flow.sort((left, right) => left.order - right.order);
+}
+
+export function objectValue(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+export function stringValue(record: Record<string, unknown> | null, ...keys: string[]): string | undefined {
+  for (const key of keys) if (typeof record?.[key] === 'string' && record[key]) return record[key] as string;
+  return undefined;
+}
+
+/** Read only top-level JSON string values, including an unfinished final string.
+ * This never executes input or mistakes escaped/nested content for a path field. */
+export function inputFields(raw: string): Record<string, unknown> {
+  try { return objectValue(JSON.parse(raw)) ?? {}; } catch { /* an in-flight argument is normally incomplete */ }
+  const fields: Record<string, unknown> = Object.create(null);
+  const prefix = raw.slice(0, 262144);
+  let depth = 0;
+  let key: string | undefined;
+  for (let index = 0; index < prefix.length; index++) {
+    const char = prefix[index];
+    if (char === '{' || char === '[') { depth++; continue; }
+    if (char === '}' || char === ']') { depth--; continue; }
+    if (char !== '"') continue;
+    const start = index;
+    let closed = false;
+    for (index++; index < prefix.length; index++) {
+      if (prefix[index] === '\\') { index++; continue; }
+      if (prefix[index] === '"') { closed = true; break; }
+    }
+    if (depth !== 1) continue;
+    const token = prefix.slice(start, closed ? index + 1 : prefix.length);
+    let value: string;
+    try { value = JSON.parse(token); } catch {
+      if (closed) continue;
+      // Strip only an unfinished trailing escape/unicode escape, not content.
+      let body = token.slice(1);
+      const unicode = /(?<!\\)(?:\\\\)*\\u[\da-f]{0,3}$/i.exec(body);
+      if (unicode) body = body.slice(0, unicode.index) + unicode[0].replace(/\\u[\da-f]{0,3}$/i, '');
+      let slashes = 0; for (let end = body.length - 1; end >= 0 && body[end] === '\\'; end--) slashes++;
+      if (slashes % 2) body = body.slice(0, -1);
+      try { value = JSON.parse(`"${body}"`); } catch { continue; }
+    }
+    if (closed && /^\s*:/.test(prefix.slice(index + 1))) key = value;
+    else if (key !== undefined) { fields[key] = value; key = undefined; }
+  }
+  return fields;
+}
+
+export function toolIdentity(entry: Pick<ToolActivityEntry, 'block' | 'draft'>) {
+  const block = entry.block;
+  return {
+    name: block ? 'kind' in block ? block.call?.name ?? entry.draft?.name ?? '工具调用' : block.name : entry.draft?.name ?? '工具调用',
+    raw: block ? 'kind' in block ? block.call?.argsRaw ?? entry.draft?.argsRaw ?? '' : block.argsRaw : entry.draft?.argsRaw ?? '',
+  };
+}
+
+export function executionFacts(block: ToolCallBlock | undefined): { exitCode?: number; signal?: string } {
+  if (!block || !('kind' in block)) return {};
+  const meta = objectValue(block.meta);
+  const code = meta?.exitCode ?? meta?.exit_code;
+  const text = block.content.length === 1 && block.content[0]?.type === 'text' ? block.content[0].text : '';
+  const exit = /\n\[exit code: (\d+)\]$/.exec(text);
+  const signal = /\n\[killed by signal: ([^\]\n]+)\]$/.exec(text);
+  const parsedCode = exit?.[1] === undefined ? undefined : Number(exit[1]);
+  return {
+    exitCode: typeof code === 'number' && Number.isFinite(code) ? code : parsedCode,
+    signal: stringValue(meta, 'signal') ?? signal?.[1],
+  };
+}
+
+export function activityPhase(entry: Pick<ToolActivityEntry, 'block' | 'draft'>, turnClosed = false): ToolPhase {
+  if (!entry.block) return turnClosed ? 'interrupted' : 'preparing';
+  if (!('kind' in entry.block)) return turnClosed ? 'interrupted' : 'running';
+  // RC1 publishes canonical cancellation as an error result with a typed code.
+  if (entry.block.error?.code === 'ABORTED' || entry.block.error?.code === 'interrupted') return 'interrupted';
+  const facts = executionFacts(entry.block);
+  if (entry.block.isError || facts.signal || (facts.exitCode !== undefined && facts.exitCode !== 0)
+    || entry.block.subCalls.some(block => activityPhase({ block }, turnClosed) === 'failed')) return 'failed';
+  if (facts.exitCode === 0) return 'succeeded';
+  return 'returned';
+}
+
+export function activitySummary(entry: Pick<ToolActivityEntry, 'block' | 'draft'>) {
+  const { name, raw } = toolIdentity(entry);
+  const args = inputFields(raw);
+  const target = stringValue(args, 'file_path', 'path', 'filename', 'filePath');
+  const command = stringValue(args, 'command', 'cmd', 'script');
+  const description = stringValue(args, 'description');
+  const file = target?.split(/[/\\]/).at(-1);
+  const category: ToolCategory = /^(write|edit|apply_patch|patch|str_replace_editor)$/.test(name) ? 'write'
+    : /^(read|read_file)$/.test(name) ? 'read'
+    : /^(bash|shell|terminal|terminal_send|exec_command|pwsh)$/.test(name) ? 'terminal'
+    : /^(grep|glob|find|search)$/.test(name) ? 'search'
+    : /^(web_search|web_fetch|web_open)$/.test(name) ? 'web' : 'other';
+  const title = category === 'write' ? `${name === 'write' ? '写入' : '修改'}${file ? ` ${file}` : name === 'apply_patch' ? '代码补丁' : '文件'}`
+    : category === 'read' ? `读取${file ? ` ${file}` : '文件'}`
+    : category === 'terminal' ? description || '运行命令'
+    : category === 'search' ? name === 'glob' ? '查找文件' : '搜索内容'
+    : category === 'web' ? name === 'web_search' ? '搜索网页' : '读取网页'
+    : name;
+  return { name, raw, args, category, title, target: target ?? command ?? stringValue(args, 'query', 'pattern', 'url'), command,
+    cwd: stringValue(args, 'workdir', 'cwd'), content: stringValue(args, 'content', 'new_string', 'newText', 'file_text') };
+}
+
+export function preparingLabel(name: string): string {
+  return /^(write|edit|apply_patch)$/.test(name) ? '正在生成文件内容' : /^(bash|shell|exec_command|pwsh)$/.test(name) ? '正在准备命令' : '正在准备工具输入';
+}

package/src/client/types.ts

@@ -0,0 +1,66 @@
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { AssistantBlock } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives';
+import type { PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
+import type {} from '@deepseek-ai/dsh-client-ui-chat/client';
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type {} from '@deepseek-ai/dsh-client-ui-session/client';
+import type { createReaderStore } from './store.js';
+
+export interface ReaderBlockOwner {
+  block: AssistantBlock;
+  streaming: boolean;
+  source: 'assistant' | 'user' | 'tool';
+}
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /** Trusted installed renderers may opt in; unknown model payloads never execute code. */
+    'dsh-better-display.block': { kind: 'chain'; scope: 'session'; owner: ReaderBlockOwner };
+  }
+}
+
+export interface ReaderInjected {
+  loadOlder: () => Promise<void>;
+  loadImage: (attachment: ImageAttachmentRef) => Promise<{ data: Uint8Array; mediaType: string }>;
+  /**
+   * Writes text into this session's composer draft via the sanctioned
+   * conversation input face, with a DOM fallback. Returns true when the
+   * composer accepted the text.
+   */
+  fillComposer: (text: string) => boolean;
+  /** Open a workspace file or directory; mode comes from the Better Display setting. */
+  openFile: (path: string) => Promise<void> | void;
+  /** Root-scoped open-mode snapshot (`dsh.reader.v1`), shared with Settings. */
+  openPrefs?: {
+    getSnapshot: () => { deliverableOpenMode?: import('./open-file.js').DeliverableOpenMode };
+    subscribe: (fn: () => void) => () => void;
+  };
+  /** Reveal and highlight a workspace file in macOS Finder or Windows Explorer. */
+  revealFile?: (path: string) => Promise<void> | void;
+  /** Fork the conversation at a specific message sequence into a new branch session. */
+  forkAt?: (seq: number) => void;
+  /** Load session history through a target sequence number. */
+  loadThrough?: (seq: unknown) => Promise<void>;
+}
+export type ReaderProps = PropsRuntime<'conversation.view'>
+  & PropsLocale<'chat'>
+  & PropsRenderSlots<'dsh-better-display.block'>
+  & PropsStore<ReturnType<typeof createReaderStore>>
+  & ReaderInjected;
+export type BlockRenderProps = Pick<ReaderProps, 'renderSlotChain' | 'loadImage' | 'fillComposer'> & {
+  openFile?: (path: string) => Promise<void> | void;
+  revealFile?: (path: string) => Promise<void> | void;
+  forkAt?: (seq: number) => void;
+  /** Durable closing-message seq of this turn (turn-tail closing), used as the fork anchor. */
+  forkSeq?: number;
+  fileMentions?: MarkdownFileMentions;
+  metrics?: {
+    usage?: NonNullable<import('@deepseek-ai/dsh-client-ui-chat/client').TurnTailChatData['tokenUsage']>;
+    runMs?: number;
+    tokensPerSecond?: number;
+    ttftMs?: number;
+    /** Closing assistant-message time (turn-tail `closing.time`). */
+    endedAt?: number;
+  };
+};

package/src/client/waiting-clock.ts

@@ -0,0 +1,25 @@
+export interface WaitingAnchor { key: string; time: number | null }
+type InputNode = { kind: string; data: unknown };
+type Submission = { requestId: string; time?: number; placement?: string };
+const timestamp = (value: number | undefined): number | null => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+
+/** Waiting is scoped to the latest human input, never the enclosing turn. */
+export function waitingAnchor(order: readonly string[], get: (key: string) => InputNode | undefined, pending: readonly Submission[] = []): WaitingAnchor {
+  let anchor: WaitingAnchor = { key: 'unresolved', time: null };
+  for (let i = order.length - 1; i >= 0; i--) {
+    const node = get(order[i]);
+    if (node?.kind === 'user' || node?.kind === 'steering') {
+      const time = node.data && typeof node.data === 'object' && 'time' in node.data && typeof node.data.time === 'number' ? node.data.time : undefined;
+      anchor = { key: order[i], time: timestamp(time) };
+      break;
+    }
+  }
+  for (let i = pending.length - 1; i >= 0; i--) {
+    const input = pending[i];
+    if (input.placement === 'queued') continue;
+    const time = timestamp(input.time);
+    if (time === null || anchor.time === null || time >= anchor.time) return { key: `pending:${input.requestId}`, time };
+    break;
+  }
+  return anchor;
+}

package/src/client/word-motion.tsx

@@ -0,0 +1,91 @@
+import { createContext, useContext, useLayoutEffect, useMemo, useRef } from 'react';
+import type { ReactNode, RefObject } from 'react';
+import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives';
+import { MarkdownText } from './markdown/MarkdownText.js';
+import { WORD_MOTION, WordTimeline } from './word-timeline.js';
+import css from './Reader.module.css';
+
+const WordScope = createContext({ enabled: false, generation: 0 });
+const CODE_LABELS = { copyLabel: '复制代码', copiedLabel: '已复制' };
+
+function useSourceReveal(element: RefObject<HTMLElement>, born: number | null, generation: number) {
+  const scope = useContext(WordScope);
+  const cancelled = useRef(false);
+  useLayoutEffect(() => {
+    const target = element.current;
+    if (!target) return;
+    target.dataset.wordState = 'settled';
+    if (!scope.enabled || scope.generation !== generation) { cancelled.current = true; return; }
+    if (cancelled.current || born === null || document.hidden) return;
+    const age = Number(document.timeline.currentTime ?? performance.now()) - born;
+    if (age >= WORD_MOTION.duration || typeof target.animate !== 'function') return;
+    // The reference opacity + blur frames, applied only to this new word.
+    // No color interpolation, stylesheet mutation, or whole-paragraph wipe.
+    const animation = target.animate([
+      { opacity: 0, filter: `blur(${WORD_MOTION.blur}px)` },
+      { opacity: 1, filter: 'blur(0px)' },
+    ], { duration: WORD_MOTION.duration, easing: WORD_MOTION.easing, fill: 'backwards' });
+    // One absolute clock prevents newly mounted/resegmented leaves from getting
+    // a fresh delay or running ahead because their layout effects ran later.
+    animation.startTime = born;
+    target.dataset.wordState = 'resolving';
+    const finish = () => { animation.cancel(); target.dataset.wordState = 'settled'; document.removeEventListener('visibilitychange', hidden); };
+    animation.onfinish = finish;
+    const hidden = () => { if (document.hidden) { cancelled.current = true; finish(); } };
+    document.addEventListener('visibilitychange', hidden);
+    return () => { animation.cancel(); document.removeEventListener('visibilitychange', hidden); target.dataset.wordState = 'settled'; };
+  }, [element, born, generation, scope.enabled, scope.generation]);
+}
+
+function Word({ children, born, generation, offset, inline }: { children: string; born: number | null; generation: number; offset: number; inline: boolean }) {
+  const element = useRef<HTMLSpanElement>(null);
+  useSourceReveal(element, born, generation);
+  return <span ref={element} className={inline ? css.streamInlineWord : css.streamWord} data-reader-word data-source-start={offset} data-source-birth={born ?? undefined}>{children}</span>;
+}
+
+/** A native code block enters on the same clock, without rebuilding its text. */
+function MotionAtom({ children, born, generation, offset }: { children: ReactNode; born: number | null; generation: number; offset: number }) {
+  const element = useRef<HTMLDivElement>(null);
+  useSourceReveal(element, born, generation);
+  return <div ref={element} className={css.streamAtom} data-reader-atom data-source-start={offset} data-source-birth={born ?? undefined}>{children}</div>;
+}
+
+/** Native Think is literal text, not Markdown. Spans never alter its bytes. */
+export function MotionPlainText({ text, enabled, revision }: { text: string; enabled: boolean; revision: number }) {
+  const timeline = useRef<WordTimeline>();
+  timeline.current ??= new WordTimeline();
+  timeline.current.begin(text, enabled, revision, Number(document.timeline.currentTime ?? performance.now()));
+  const current = timeline.current;
+  const generation = current.generation;
+  const scope = useMemo(() => ({ enabled, generation }), [enabled, generation]);
+  return <WordScope.Provider value={scope}><div className={css.reasonPlain}>
+    {current.hasLiveText ? current.words(text, 0).map(word => word.text.trim()
+      ? <Word key={word.key} born={word.born} generation={generation} offset={word.key} inline>{word.text}</Word>
+      : word.text) : text}
+  </div></WordScope.Provider>;
+}
+
+/** Native DSH Markdown semantics with a stable text-leaf animation hook. */
+export function MotionMarkdown({ text, streaming, enabled, revision, fileMentions }: {
+  text: string; streaming: boolean; enabled: boolean; revision: number; fileMentions?: MarkdownFileMentions;
+}) {
+  const timeline = useRef<WordTimeline>();
+  timeline.current ??= new WordTimeline();
+  timeline.current.begin(text, enabled, revision, Number(document.timeline.currentTime ?? performance.now()));
+  const generation = timeline.current.generation;
+  const scope = useMemo(() => ({ enabled, generation }), [enabled, generation]);
+  const renderText = useMemo(() => (value: string, offset: number, inline = false): ReactNode => {
+    const current = timeline.current!;
+    if (!current.hasLiveText) return value;
+    return current.words(value, offset).map(word => word.text.trim()
+      ? <Word key={word.key} born={word.born} generation={current.generation} offset={word.key} inline={inline || /^\p{P}+$/u.test(word.text)}>{word.text}</Word>
+      : word.text);
+  }, []);
+  const renderAtom = useMemo(() => (children: ReactNode, offset: number): ReactNode => {
+    const current = timeline.current!;
+    return current.hasLiveText ? <MotionAtom born={current.bornAt(offset)} generation={current.generation} offset={offset}>{children}</MotionAtom> : children;
+  }, []);
+  return <WordScope.Provider value={scope}>
+    <MarkdownText text={text} streaming={streaming} codeLabels={CODE_LABELS} fileMentions={fileMentions} renderText={renderText} renderAtom={renderAtom} />
+  </WordScope.Provider>;
+}

package/src/client/word-timeline.ts

@@ -0,0 +1,96 @@
+/** Motion parameters from the public transitions.dev streaming-text recipe. */
+export const WORD_MOTION = {
+  duration: 350,
+  gap: 60,
+  blur: 1,
+  easing: 'cubic-bezier(0.22, 1, 0.36, 1)',
+  maxDelay: 240,
+} as const;
+
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'word' });
+const closingPunctuation = /^[\p{Pe}\p{Pf},.!?:;，。！？、；：％‰…·]+$/u;
+const openingPunctuation = /^[\p{Ps}\p{Pi}]+$/u;
+export interface RevealingWord { key: number; text: string; born: number | null }
+interface SourceBirth { end: number; born: number | null }
+
+/** Source-offset identity survives reparsing, frozen blocks, and final formatting. */
+export class WordTimeline {
+  generation = 0;
+  hasLiveText = false;
+  private source: string | null = null;
+  private enabled = false;
+  private revision = 0;
+  private floor = 0;
+  private lastBirth = -Infinity;
+  private readonly births: SourceBirth[] = [];
+
+  begin(source: string, enabled: boolean, revision: number, now: number): void {
+    if (this.source === source && this.enabled === enabled && this.revision === revision) return;
+    const replaced = revision !== this.revision || (this.source !== null && !source.startsWith(this.source));
+    if (replaced || !enabled) {
+      this.births.length = 0;
+      this.lastBirth = -Infinity;
+      this.generation++;
+      this.floor = source.length;
+    } else if (this.source === null) {
+      // A mounted historical prefix must not replay; a fresh live buffer mounts empty.
+      this.floor = source.length;
+    } else {
+      // Allocate in source order, before Markdown can split/reorder text leaves.
+      // Intervals cover every offset, so resegmented CJK words inherit the time
+      // of their characters rather than falling through as instant "history".
+      const from = this.source.length;
+      for (const part of segmenter.segment(source.slice(from))) {
+        let born = Number.isFinite(this.lastBirth) ? this.lastBirth : null;
+        if (part.segment.trim()) {
+          born = Math.min(now + WORD_MOTION.maxDelay, Math.max(now, this.lastBirth + WORD_MOTION.gap));
+          this.lastBirth = born;
+        }
+        const end = from + part.index + part.segment.length;
+        const previous = this.births.at(-1);
+        if (previous && previous.born === born) previous.end = end;
+        else this.births.push({ end, born });
+      }
+    }
+    this.source = source;
+    this.enabled = enabled;
+    this.revision = revision;
+    this.hasLiveText = enabled && this.births.length > 0;
+  }
+
+  bornAt(offset: number): number | null {
+    if (!this.enabled || offset < this.floor || this.births.length === 0) return null;
+    let low = 0;
+    let high = this.births.length - 1;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      if (this.births[middle]!.end <= offset) low = middle + 1;
+      else high = middle;
+    }
+    return this.births[low]!.born;
+  }
+
+  words(value: string, offset: number): RevealingWord[] {
+    // Atomic inline animation boxes must not turn commas into legal line starts
+    // or strand opening quotes at a line end. Keep source-offset identities when
+    // punctuation arrives in a later chunk, so the preceding word never replays.
+    // Already received text is one inert leaf, not thousands of React Words.
+    // Only the newly appended suffix needs word identities and birth times.
+    const prefixLength = Math.min(value.length, Math.max(0, this.floor - offset));
+    const prefix: RevealingWord[] = prefixLength > 0
+      ? [{ key: offset, text: value.slice(0, prefixLength), born: null }]
+      : [];
+    const parts: { index: number; segment: string }[] = [];
+    for (const segment of segmenter.segment(value.slice(prefixLength))) {
+      const part = { index: prefixLength + segment.index, segment: segment.segment };
+      const previous = parts.at(-1);
+      if (previous?.segment.trim() && (closingPunctuation.test(part.segment) || openingPunctuation.test(previous.segment))) {
+        previous.segment += part.segment;
+      } else parts.push({ index: part.index, segment: part.segment });
+    }
+    return prefix.concat(parts.map(part => {
+      const key = offset + part.index;
+      return { key, text: part.segment, born: this.bornAt(key) };
+    }));
+  }
+}

package/src/dsh-better-display.ts

@@ -0,0 +1,108 @@
+import { spawn } from 'node:child_process';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import { scanGenerativeMcpappsStatus } from './skill-roots.js';
+import { skillsFromListResult, toPublicSkillStatus } from './skill-status.js';
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    webServer?: {
+      register: (route: {
+        kind: 'exact' | 'prefix';
+        path: string;
+        handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+      }) => () => void;
+    };
+  }
+}
+
+export const name = 'dsh-better-display';
+export const inject = ['webServer'];
+
+function writeJson(res: ServerResponse, status: number, body: unknown): void {
+  res.setHeader('Content-Type', 'application/json');
+  res.statusCode = status;
+  res.end(JSON.stringify(body));
+}
+
+function skillLister(ctx: Context): (() => Promise<readonly { readonly name?: string }[] | undefined>) | undefined {
+  const skills = ctx.get?.('skills') as { list?: (options?: object) => Promise<unknown> } | undefined;
+  if (typeof skills?.list !== 'function') return undefined;
+  return async () => skillsFromListResult(await skills.list!({}));
+}
+
+export function apply(ctx: Context): void {
+  console.log('[my-plugins/dsh-better-display] loaded');
+
+  if (ctx.webServer) {
+    ctx.effect(() => {
+      const disposeReveal = ctx.webServer!.register({
+        kind: 'exact',
+        path: '/better-display/reveal',
+        handler: async (req, res) => {
+          if (req.method !== 'POST') {
+            res.statusCode = 405;
+            res.end();
+            return;
+          }
+          let body = '';
+          req.on('data', chunk => { body += chunk; });
+          req.on('end', () => {
+            try {
+              const data = JSON.parse(body);
+              const targetPath = typeof data.path === 'string' ? data.path.trim() : '';
+              if (!targetPath) {
+                res.statusCode = 400;
+                res.end(JSON.stringify({ ok: false, error: 'Empty path' }));
+                return;
+              }
+
+              if (process.platform === 'darwin') {
+                // Exact file reveal in macOS Finder with selection highlight
+                spawn('open', ['-R', targetPath], { detached: true, stdio: 'ignore' });
+              } else if (process.platform === 'win32') {
+                // Exact file selection in Windows Explorer
+                spawn('explorer.exe', [`/select,${targetPath}`], { detached: true, stdio: 'ignore' });
+              } else {
+                spawn('xdg-open', [targetPath], { detached: true, stdio: 'ignore' });
+              }
+
+              res.setHeader('Content-Type', 'application/json');
+              res.statusCode = 200;
+              res.end(JSON.stringify({ ok: true }));
+            } catch (err) {
+              res.statusCode = 400;
+              res.end(JSON.stringify({ ok: false, error: String(err) }));
+            }
+          });
+        },
+      });
+      const disposeSkill = ctx.webServer!.register({
+        kind: 'exact',
+        path: '/better-display/skill-status',
+        handler: async (req, res) => {
+          if (req.method !== 'GET') {
+            res.statusCode = 405;
+            res.end();
+            return;
+          }
+          try {
+            const url = new URL(req.url ?? '', 'http://127.0.0.1');
+            const cwd = url.searchParams.get('cwd') ?? undefined;
+            const status = await scanGenerativeMcpappsStatus({
+              cwd,
+              listSkills: skillLister(ctx),
+            });
+            writeJson(res, 200, toPublicSkillStatus(status));
+          } catch (err) {
+            writeJson(res, 500, { ok: false, error: String(err) });
+          }
+        },
+      });
+      return () => {
+        disposeReveal();
+        disposeSkill();
+      };
+    }, 'dsh-better-display: reveal and skill-status routes');
+  }
+}