dsh-better-display 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## Unreleased
+
+- Add a Better Display settings section: deliverables still open in the system app by default, with an optional right-Sidebar preview, plus generative-mcpapps skill-root detection and install guidance.
+- Guard pending-submission image echoes so a text-only send cannot crash `conversation.view` (`images` / `attachments` may be missing).
+- Install guidance names only conventional relative roots (`.dsh/skills`, `.agents/skills`) and never prints host home or plugin pack absolutes.
+- Keep ChatView's `data-chat-flow=""` hook on the Reader column so skins that hide `[data-composer-seat]` when the scrollport has no chat-flow (maid-atelier, phoebe-atelier, and others) still show the composer in reading view.
+
+## 0.1.1 — 2026-09-16
+
+The accepted reading-view integration, including the work consolidated from PRs #2, #5 and #8. Earlier `0.2.0` / `0.2.1` headings were unpublished development notes; those changes ship in this release, not as separate published versions.
+
+### Reading and folding
+
+- A later reasoning step can fold earlier steps in its chain into a compact count summary. Body/tool updates alone do not trigger folding; user/steering input resets the chain. The auto-fold control can disable this presentation.
+- Stable keyed rows shrink before counters update, pause briefly, then reveal buffered output. Preserve source order, selected text, reduced-motion behavior, and the visible final answer.
+- Keep process statistics after turn completion. Empty hidden steps no longer accumulate 16px gaps in long completed turns.
+- Give the auto-fold control a full-width, seamless lane without divider lines or replacement shadows. Statistics remain in normal flow until reaching the top, then stick below the measured status lane, whether expanded or collapsed.
+- Short status labels remain readable instead of truncating. Waiting time resets to the latest user/steering submission rather than inheriting the turn's original start time.
+
+### Navigation and native parity
+
+- Keep the newer TimelineRail, including incremental history loading, per-turn metrics, fork support, and composer-safe landing. Scroll the conversation container rather than unrelated ancestor boxes.
+- Skip host-synthetic `turn-process` JSON cards; render `/goal` command input as labeled text; give system-prompt details their own scrollport.
+- Use the compact back-to-bottom chevron at the native near-bottom threshold and coalesce scroll-anchor capture.
+- Show user-message time/copy controls and turn-end duration; defer produced-file rows until the turn closes.
+
+### Interactive content
+
+- Render generative MCP Apps from supported code fences, custom blocks, and tool results through an isolated iframe (`sandbox="allow-scripts allow-forms"`, no `allow-same-origin`).
+- Support SEP-1865 JSON-RPC initialization, sizing, context updates, and prompt feedback into the composer, with light/dark synchronization and bounded auto-height.
+- Include the generative-mcpapps skill pack, examples, and bilingual documentation.
+
+### Distribution and verification
+
+- Target DeepSeek Harness 0.1.5-rc.2 through public plugin/client extension points. No Agent, SDK, provider, credential, or Harness-core changes.
+- Ship the stock-install bundle patch and rebuilt committed `lib/`, including declarations; git/tarball installation does not require `prepare`.
+- Add fold-order/timing and steering-clock unit regressions, plus real-component browser fixtures for motion, 500 hidden rows, sticky/wrapped statistics, and waiting-clock resets.
+
+## 0.1.0
+
+First public release of the accepted reading-view plugin, published as `dsh-better-display`.
+
+- Native context and tool details with source-ordered, unmodified reasoning.
+- Bounded long-reasoning cards with two-line following, expanded follow and manual pause/resume.
+- Successful-turn process folding with a separate final answer.
+- Source-ordered text reveal and quiet busy-state shimmer.
+- Stable status typography and compact disclosure spacing.
+- Native content fallbacks and a trusted-plugin block extension slot.
+- 42 regression tests; no changes to DSH Agent, SDK, providers or core.

package/DESIGN.md

@@ -0,0 +1,72 @@
+# Display contract
+
+## Purpose
+
+Keep native DeepSeek Harness process information readable while separating the final answer after a successful turn. The reading view is a presentation of the public session projection, never a second Agent pipeline.
+
+## Content fidelity
+
+- Preserve literal reasoning text, whitespace, source order and block identity.
+- Do not infer reasoning from wording, parse private provider logs, rewrite prompts or alter model settings.
+- Preserve native context sources, tool types, summaries, filenames, details and results.
+- Preserve the native conversation, input, model selector and approval system.
+- Leave nontext and unknown content available through native renderers or a safe fallback.
+
+## Lifecycle
+
+During a turn, show its real process in chronological order. Starting body output, preparing tool input, finishing one tool, or entering another step is not whole-turn completion.
+
+Only a successful public turn-close boundary folds process and intermediate commentary, leaving the final answer in place. Failures, interruptions, unknown terminal states and approval requests remain visible. A live text selection defers folding until the selection is released. A historical turn can always be reopened.
+
+While a turn is still open, a later reasoning step may collapse earlier steps of the same chain into one disclosure (`思考×N`). Body or tool alone never triggers that live fold. A mid-turn user insert or steering message resets the chain. This is presentation-only and does not change the successful-turn final-answer fold.
+
+## Long reasoning
+
+A neutral card bounds the transcript without replacing it. The viewport mask is 28px. Follow advances by two actual line heights every 840ms, with a 500ms transform using `cubic-bezier(.22,1,.36,1)`; clamp only at the current real end. Never accelerate through a burst, clone the transcript or loop old text.
+
+Expanding changes viewport size and preserves position and follow state. Wheel, touch, viewport focus or selection pause following. The explicit follow control resumes only when no text is selected. Completed history stays static. The full source text remains available.
+
+## Text and status motion
+
+Assign reveal times from source positions before rendering Markdown. Only newly appended text receives opacity/blur motion; existing paragraphs, page surfaces and text color do not animate. Unicode graphemes and punctuation keep their source order. Media and custom blocks do not enter the text queue.
+
+Busy labels use a 2-second glyph-only shimmer and a short state swap. Initial, busy and elapsed labels all use the native font at 14px/24px, weight 400. The disclosure arrow sits 6px from the current label; no longest-state spacer. Elapsed time and attention states do not shimmer.
+
+## Sticky reading lanes (2026-09-16)
+
+Keep the existing in-flow positions. The auto-fold control receives a full-column, 40px-minimum lane from initial render, native page background and seamless spacing, without divider lines or replacement shadows (user preference). The status retains its source position and shares the top lane's left side only when it reaches the scrollport top. The original summary row (never a duplicate) sticks below the greater measured toolbar/status height. Expanded and collapsed live summaries remain discoverable; completed summaries obey the same sticky offset. Scope is the current flow/turn, so subsequent turns replace earlier statistics rather than displaying unrelated counts forever.
+
+Taste checkpoint: native reading chrome, not floating badges; one column, no new card family, no shadows or rounded background tiles; existing typography. Active responsive-interaction binding: real ResizeObserver lane geometry → StickyLane + CSS offsets → verify desktop/320px, wrapped statistics, no overlap, and return to original position on reverse scroll. Preserve prior measured fold choreography and zero-height empty wrappers.
+
+## Reading and accessibility
+
+Manual reading, selection and keyboard access take precedence over automatic following. Reduced-motion preferences, disabled motion and background views settle to the received content. Errors stay local to their block. Do not turn user interaction into a permanent lock that prevents successful-turn folding.
+
+## Extensions and safety
+
+Trusted plugins may register `dsh-better-display.block`. Native content remains the fallback. Generative MCP Apps (SEP-1865 / `io.modelcontextprotocol/ui`) are supported via an isolated, sandboxed iframe (`sandbox="allow-scripts allow-forms"`, strictly without `allow-same-origin`) communicating via bidirectional JSON-RPC `postMessage` (`ui/initialize`, `ui/resize`, `ui/update-model-context`, `ui/submit`).
+
+## Host DOM hooks
+
+Reader replaces ChatView's message list, not the native conversation chrome. The enclosing `[data-conversation-scroll]` and sticky `[data-composer-seat]` stay host-owned. ChatView marks its column with `data-chat-flow=""`. Third-party skins (maid-atelier, phoebe-atelier, and others) treat a scrollport without that hook as inspect-only and hide the composer. Reader keeps the same empty `data-chat-flow` attribute on its column so those skins still see an interactive conversation. Turns stay on `[data-reader-turn]`; Reader does not emit native `[data-chat-flow-kind]` rows.
+
+## Fold choreography contract (2026-09-16)
+
+Single-agent implementation; preserve existing type, colors, source order and one-column reading layout. The memory cue is causality, not ornament: shrink → count → pause → continue. No bouncing capsule, scale-squashed text or parallel entrance spectacle.
+
+| Active reference | Decision | Target | Verification |
+| --- | --- | --- | --- |
+| motion-language | One attention owner; bounded coalescing instead of replaying every arrival | ChoreographedFlow | fast/slow/burst frame samples |
+| motion-contract | Preserve step parents/keys until shrink completes; freeze a materialized public snapshot | fold-choreography + ChoreographedFlow | DOM identity, intermediate heights, ordered phases |
+| responsive-interaction | Controls stay usable; labels receive available width, not an arbitrary narrow box | Reader.module.css | wide/narrow/200% text checks |
+| typography-system | Keep native 14/24 status type; full short labels; wrap exceptional long labels | StatusText CSS | actual range vs container bounds |
+
+Motion id: `fold-choreography`. Trigger: newly received reasoning folds a previously visible chain. Historical mount is static. Native WAAPI animates measured layout height for 320ms (deliberate layout exception needed for real flow continuity), then counters roll for 160ms, then 80ms stillness, then 180ms content reveal. New data coalesces into one latest frame; it never restarts the active shrink. Newly released text uses the existing grapheme-safe bounded catch-up buffer. Counter values belong to committed presentation frames, not the transport clock.
+
+A selected passage, new user message, approval, error, stop, reduced motion or hidden page bypasses the waiting queue. Manual fold controls remain interruptible. Only the reader scroll coordinator writes the outer scroll position; during measured size animation it tracks geometry rather than layering another scroll easing. Authoritative session data is never rewritten.
+
+Rollback baseline: `.delivery/before-choreography-20260916.tgz` plus original commit `56a87bb2531e5ccb9db5d4c8a347c2f91d7e449a`; existing uncommitted fixes are included in the archive. Changed surface: existing client only, no Host restart or core edits.
+
+## Verification
+
+Use unit coverage for projection, lifecycle, source-ordered streaming, graphemes, Markdown and two-line stepping. Verify live Host manifest, served bundle, native process details, literal reasoning, motion, successful folding, reopening, narrow layouts and reduced motion separately. Keep private session evidence outside this repository.

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 dsh-better-display contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Third-party material retains its original license and terms as identified in
+THIRD_PARTY_NOTICES.md. This license does not relicense that material.

package/README.en.md

@@ -0,0 +1,41 @@
+# dsh-better-display
+
+[中文](./README.md)
+
+```sh
+dsh plugin --profile web add github:aa2246740/dsh-better-display
+```
+
+You need official `dsh` (or `npx @deepseek-ai/dsh`) and **pnpm** on PATH. `dsh plugin add` runs pnpm in `$DSH_HOME/profiles/web`. This repo commits built `lib/`, so a git install does not need `prepare` or a profile `allowBuilds` entry.
+
+Then restart that Host and reload the page. `dsh plugin add` writes the profile. It does not hot-load a running process.
+
+Adds a **阅读** tab to DeepSeek Harness. While a turn runs you see steps, thinking, and progress. After a successful turn those collapse and the final answer stays. Native Chat / Trajectory, the composer, model picker, tools, and approvals stay. The reading column keeps ChatView's `data-chat-flow` hook so third-party skins that gate the composer on that mark still treat Reader as an interactive conversation.
+
+A ````mcp-app` fence in the final answer mounts as an interactive card in the reading view, inside `<iframe sandbox="allow-scripts allow-forms">` without `allow-same-origin`. The card can fill the next prompt via JSON-RPC. The skill pack is [`skills/generative-mcpapps/`](skills/generative-mcpapps/). Settings → **Better Display** can preview deliverables in the right Sidebar (system app remains the default) and reports whether that skill is installed in a harness skill root.
+
+Targets DeepSeek Harness **0.1.5-rc.2**. Display only. It does not change Agent execution, the SDK, or credentials. Node.js `^22.19.0 || >=24`. New sessions default to reading.
+
+From a local checkout or tarball:
+
+```sh
+dsh plugin --profile web add ./dsh-better-display
+dsh plugin --profile web add ./dsh-better-display-0.1.1.tgz
+```
+
+`dsh.bundle` is captured at Host boot. Do not also insert the same row by hand in the profile `cordis.patch.yml`, or it will mount twice.
+
+```sh
+dsh plugin --profile web remove dsh-better-display
+```
+
+## Develop
+
+```sh
+npm test
+npm run typecheck
+```
+
+## License
+
+Display and Markdown pieces come from DeepSeek Harness (MIT). Motion is based on [Transitions.dev](https://transitions.dev/). This repo is [MIT](LICENSE).

package/README.md

@@ -0,0 +1,41 @@
+# dsh-better-display
+
+[English](./README.en.md)
+
+```sh
+dsh plugin --profile web add github:aa2246740/dsh-better-display
+```
+
+PATH 上要有官方 `dsh`（没有就用 `npx @deepseek-ai/dsh`）和 **pnpm**。`dsh plugin add` 会在 `$DSH_HOME/profiles/web` 里跑 pnpm。仓库已提交编译好的 `lib/`，git 安装不用 `prepare`，也不用改 profile 的 `allowBuilds`。
+
+然后重启这个 Host，再刷新页面。`dsh plugin add` 只写 profile，不会热挂正在跑的进程。
+
+给 DeepSeek Harness 加一个 **阅读** 页签：执行时能看到步骤、思考和进度；整轮成功结束后把过程收起来，留下最终回答。原版「对话 / 轨迹」、输入框、模型选择、工具和审批都还在。阅读列保留宿主 ChatView 的 `data-chat-flow` 钩子，依赖该标记显示输入框的第三方皮肤不会把阅读页当成仅检视视图。
+
+最终回答里的 ````mcp-app` 代码块会在阅读视图里挂成交互卡片，跑在 `<iframe sandbox="allow-scripts allow-forms">` 里，没有 `allow-same-origin`。卡片可以通过 JSON-RPC 把下一轮 prompt 填进输入框。技能包在 [`skills/generative-mcpapps/`](skills/generative-mcpapps/)。设置里的 **Better Display** 可把产物改为右侧栏预览（默认仍用系统应用），并检测该技能是否已装进宿主技能目录。
+
+面向 DeepSeek Harness **0.1.5-rc.2**。只改展示，不改 Agent 执行、SDK 或模型凭据。Node.js `^22.19.0 || >=24`。新会话默认进阅读。
+
+本地目录或 tarball：
+
+```sh
+dsh plugin --profile web add ./dsh-better-display
+dsh plugin --profile web add ./dsh-better-display-0.1.1.tgz
+```
+
+`dsh.bundle` 是开机捕获的。不要再往 profile 的 `cordis.patch.yml` 手写同一条 insert，会重复挂载。
+
+```sh
+dsh plugin --profile web remove dsh-better-display
+```
+
+## 开发
+
+```sh
+npm test
+npm run typecheck
+```
+
+## 许可
+
+展示与 Markdown 部分来自 DeepSeek Harness（MIT）。动效参考 [Transitions.dev](https://transitions.dev/)。本仓库代码 [MIT](LICENSE)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,65 @@
+# Third-party notices
+
+The MIT license in this repository covers original plugin code. It does not
+replace third-party licenses or the Transitions.dev recipe terms below.
+
+## Transitions.dev product-use terms
+
+The three free recipes used in this DSH-specific display are Streaming text,
+Thinking states and Reasoning stream, by Jakub Antalik / Transitions.dev.
+They are incorporated into the actual conversation UI, not redistributed as a
+standalone effects collection, template pack or component kit. No Pro assets,
+website fonts, stock images, demo transcript or upstream CLI are included.
+
+The upstream [Terms & License](https://transitions.dev/terms.html), last updated
+July 2026 and checked on 2026-08-28, permit use, modification and shipment of
+accessible recipes within personal or commercial products. They prohibit
+republishing the collection or a substantial part as a competing effects
+library, template pack or component kit. The upstream MIT license applies to
+its tooling, **not** to the transition recipes. Retain this notice and consult
+the upstream terms when redistributing or adapting the corresponding motion
+portions of `Reader.module.css`, `motion.tsx` and `word-timeline.ts`.
+
+## DeepSeek Harness native process presentation
+
+`src/client/native` copies the native context rows, form-specific context bodies, reference icon and pure tool summary model. `upstream.json` records the source commit and each original hash. The only adaptations are public type imports, relative ESM suffixes and a local icon path. The MIT license below covers these files. No Host, model, SDK, Agent or tool execution source is included or modified.
+
+## DeepSeek Harness Markdown renderer
+
+`src/client/markdown` derives from DeepSeek Harness commit `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`. Changes add source-offset hooks for text leaves, literal HTML, inline code and atomic code-block entry, and keep source-offset keys on finalization. Native CodeBlock is reused through the public package API without changing its content renderer. Original file hashes are recorded in `upstream.json`.
+
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Transitions.dev Streaming text
+
+Motion recipe: https://github.com/Jakubantalik/transitions.dev/blob/ef497bb64867ce569689730198fc66f49db56317/cli/free/streaming-text.md
+
+Author: Jakub Antalik. The public free recipe is presented for copying into projects. Opacity 0 to 1, blur 1px to 0, 350ms, 60ms gap and cubic-bezier(0.22,1,0.36,1) are used here. The live adapter animates only appended words rather than replaying existing paragraphs. No protected recipes were retrieved and no license for the entire upstream repository is asserted.
+
+## Transitions.dev Thinking states
+
+Author: Jakub Antalik. Source: the public [Thinking states recipe](https://github.com/Jakubantalik/transitions.dev/blob/ef497bb64867ce569689730198fc66f49db56317/cli/free/thinking-states.md). The scoped implementation retains its glyph-only `::before` sweep (2 seconds, 400% background), 150ms state transition, 50ms entry gap, 8px travel and 2px blur. DSH semantic colors replace fixed colors; real Host events replace the demo's timed state carousel. Hidden visual copies are excluded from accessibility, and interrupted/off/reduced/background states settle to the current label.
+
+## Transitions.dev Reasoning stream
+
+Author: Jakub Antalik. Source: the public [Reasoning stream recipe](https://github.com/Jakubantalik/transitions.dev/blob/ef497bb64867ce569689730198fc66f49db56317/cli/free/reasoning-stream.md). This adaptation retains the 28px viewport mask, 840ms cadence, 500ms cubic-bezier(0.22,1,0.36,1) CSS transform and fixed two-line steps, clamped only at the real transcript's current end. One real text tree replaces the demo's cloned loop. Body and tool phases do not prematurely stop the current step's motion; manual reading receives the painted offset through native scrolling, preserving selection and keyboard access. Bursts never increase the step distance. Reduced motion and closed historical turns remain static.

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Official bundle layer. `dsh plugin add` applies this into the profile.
+# Rows resolve by package name so the installed copy is what boots.
+- insert:
+    - id: dsh-better-display
+      name: dsh-better-display

package/cordis.yml

@@ -0,0 +1,4 @@
+# Source overlay for local --patch work. Stock install uses cordis.patch.yml.
+- insert:
+    - id: dsh-better-display
+      name: './src/dsh-better-display.ts'

package/dshx.yml

@@ -0,0 +1,5 @@
+id: dsh-better-display
+entry: src/dsh-better-display.ts
+marker: '[my-plugins/dsh-better-display] loaded'
+kind: client
+profile: web