Aafff623/dsh-callout

dsh-callout

GitHub-style alert cards for DeepSeek Harness (DSH) assistant Markdown. It turns a qualifying > [!NOTE] blockquote into a compact, theme-aware card without changing stored session content or DSH's core renderer.

See it first

> [!WARNING]
> This operation may overwrite existing configuration.

Install the plugin, refresh DSH Web, then send that assistant Markdown. A qualifying leading marker becomes a warning card; malformed or unknown markers remain ordinary text.

Why this plugin exists

A warning should look like a warning before the reader reaches the command. A key decision should be easy to find without wrapping the entire answer in a colored box.

dsh-callout keeps the source format readable Markdown and upgrades it only at presentation time:

assistant Markdown → DSH MarkdownText → ordinary blockquote → callout card

It does not modify stored session content, providers, permissions, tools, or the DSH core renderer.

Supported types

Type	Use it for	Accent
NOTE	Premises, environment facts, and boundaries	Blue
TIP	A better or less obvious approach	Green
IMPORTANT	A decision or key conclusion	Purple
WARNING	Potential loss or destructive operations	Amber
CAUTION	High-impact or difficult-to-reverse operations	Red

Visual map

The two diagrams below keep the proof close to the implementation: the type palette shows the supported semantic cards, and the flow shows the guarded DOM upgrade path.

Install

No settings. After install, the host half injects the authoring contract into the system prompt, and the browser half upgrades qualifying assistant Markdown.

From GitHub

dsh plugin --profile web add github:Aafff623/dsh-callout

Then hard-refresh the Web UI (Ctrl+Shift+R). dsh.bundle.patch inserts the plugin into the profile bundle.

lib/ is committed, so a git install needs no local build.

npm

Not published yet. dsh plugin --profile web add dsh-callout works only after the package is on the registry you use.

Canonical syntax

Use one of these two forms:

> [!NOTE]
> Body text on the next line.

> [!NOTE] Body text on the same line.

The marker must be the first content of the blockquote. Every physical line in a multiline callout starts with >.

These are not canonical callouts:

[!NOTE] Body without the `>` marker.

Intro text > [!NOTE] > body squeezed onto one line.

Malformed or unknown markers fail open as ordinary text. The plugin does not attempt to turn every occurrence of [!NOTE] into a card.

What is guaranteed

• Five fixed types, case-insensitive.
• Code, inline code, emphasis, links, lists, nested quotes, and later paragraphs do not activate the blockquote transform.
• The marker is removed only from a qualifying leading text node; the body node is retained.
• The observer-echo path is idempotent: the plugin's own text mutation is not mistaken for an edit.
• Real edits can remove plugin-owned card chrome and restore the source marker when it is still safe to do so.
• Light/dark palette rules follow DSH's body[data-ds-dark-theme] switch.

What this plugin does not do

• Human messages are rendered by DSH as plain text and are intentionally outside this plugin's scope.
• It is not a Markdown parser replacement and does not add new Markdown AST node types.
• It does not guarantee source-level distinction between a real marker and a backslash-escaped marker after Markdown parsing.
• The plugin uses the current DSH Web DOM contract; a future renderer change should be checked with the regression suite and a browser smoke test.

Architecture

Layer	File	Responsibility
Host	src/index.ts	Injects the concise output contract into the system prompt
Bundle	cordis.patch.yml	Registers the plugin entry in the DSH bundle
Browser	src/client/index.ts	Matches rendered DOM, applies card attributes/CSS, observes streaming updates, and owns teardown
Verification	test/callout.test.mjs	Tests GFM shapes, negative cases, and the observer state machine

Both halves build into lib/ with esbuild. The browser half is deliberately presentation-only. It uses plugin-owned data-md-alert-* attributes and --dsh-callout-* variables, and registers cleanup with Cordis ctx.effect().

Development

npm install
npm run typecheck   # tsc --noEmit
npm run build       # esbuild → lib/index.js + lib/client.js (ModuleLoader-wrapped)
npm test            # node:test, vm-isolated suite against the built bundle

lib/ is committed on purpose: a git install works with zero build step. If you change src/, run npm run build and commit the refreshed lib/ together — CI fails on drift.

The test suite currently covers 30 cases, including:

• standard one-line and multiline forms;
• all five types, lowercase types, CRLF, and CJK text;
• unknown/glued markers, code, emphasis, links, lists, nested quotes, and indented/fenced code;
• bare assistant-Markdown paragraph fallback;
• first upgrade, observer echo, real-edit cleanup, and node-removal release;
• incremental dirty-root hits, unrelated mutations that must not clear a card, and a rebuilt parent paragraph.

For a quick visual check, open demo-before-after.html. The diagrams in this README are deterministic implementation maps, not screenshots of a running session.

Compatibility and maintenance

Plugin	DSH baseline	Status
0.2.x	0.1.2-rc.1	Tested

After a DSH upgrade, run npm test, then smoke-test one standard callout, one code example, one theme switch, and one session switch. If the renderer, Markdown root class, client loader, or chat-flow attributes change, review src/client/index.ts before upgrading the plugin version.

License

MIT — see LICENSE.