jsmdcui 0.4.0 → 0.6.3

package/runtime/help/help.md

@@ -1,3 +1,20 @@
+![Demo](https://raw.githubusercontent.com/jjtseng93/jsmdcui/main/demo.jpg)
+
+# Demo App
+## My app
+
+- [Say hello](javascript:sayHello())
+- [Get server time](javascript:showServerTime())
+- [Update text box](javascript:updateText())
+- [Show selected](javascript:alert(JSON.stringify($('#my-app').val())))
+- [x] task1
+- [x] task2
+- [ ] unselected task
+
+```text#myid.myclass
+Editable in both TUI and WUI
+```
+
 # Introduction
 - jsmdcui stands for:
 - JavaScript Markdown Cross-environment User Interface
@@ -10,6 +27,12 @@
 - Original projects:
 - https://github.com/jjtseng93/bunmicro
 - https://github.com/micro-editor/micro
+- .
+- This README is itself a runnable app.
+
+```sh
+npx jsmdcui@latest README.md
+```
 
 ## Quick start
 
@@ -24,28 +47,52 @@ On other platforms, follow the [official Bun installation guide](https://bun.com
 Choose either of these two ways to run jsmdcui.
 
 > **Important:** Opening or rendering a local `.md` file writes or overwrites
-> five generated files beside it. Starting `--wui` without a file writes the
-> five files generated from `testapp.md` in the current directory. The source
+> 5 generated files beside it. Starting `--wui` without a file writes the
+> 5 files generated from `testapp.md` in the current directory. The source
 > Markdown is not changed, but you should run the demo in a directory where
 > overwriting generated files is safe.
 
 ### Route 1: Run with npx
 
-This route requires both `npx` and `bun` on your `PATH`; no source checkout is
-required. Open the normal terminal editor:
+- This route requires both `npx` and `bun` on your `PATH`; no source checkout is
+required. 
+
+#### Open the normal terminal editor
 
 ```sh
 npx jsmdcui
 ```
 
-Or start the default browser demo:
+#### Start `testapp.md` as the TUI/WUI demo
+- If `testapp.md` is missing, the bundled copy is written to the current working directory
+- If `testapp.md` already exists, it will be used and won't be overwritten.
+
+```sh
+# TUI(Terminal User Interface) Demo
+npx jsmdcui --demo
+```
+
+```sh
+# Heading and task-list selector demo
+npx jsmdcui --demo-select
+```
 
 ```sh
+# Bun.Image processor demo
+npx jsmdcui --demo-imgtool
+```
+
+```sh
+# Traditional Chinese Bun.Image processor demo
+npx jsmdcui --demo-imgtool-zh
+```
+
+```sh
+# WUI(Web User Interface) Demo
 npx jsmdcui --wui
 ```
 
-If the current directory already contains `testapp.md`, that local file is used
-instead of the bundled demo. To open your own Markdown UI, pass its path:
+#### Open your own Markdown CUI App
 
 ```sh
 npx jsmdcui app.md
@@ -60,30 +107,37 @@ cd jsmdcui
 bun src/index.js testapp.md
 ```
 
-The last command opens the included demo in the terminal. Use the arrow keys to
-move, `Enter` or `Space` to activate an item, and `Ctrl-Q` to quit. To open the
-same demo in a browser instead:
+- The last command opens the included demo in the terminal
+- Use arrow keys to move around
+- `Enter`, `Space`, or mouse click to activate an item, and `Ctrl-Q` to quit.
+- To open the same demo in a browser instead:
 
 ```sh
 bun src/index.js --wui testapp.md
 ```
 
-After starting `--wui`, open the last printed `http://...` URL in a browser.
-Keep the command running while using the page, and press `Ctrl-C` in that
-terminal to stop the server.
+- After starting `--wui`, open the last printed `http://...` URL in a browser.
+- Keep the command running while using the CUI App, and press `Ctrl-C` in that terminal to stop the server.
 
-The command table below uses the cloned-source form. If you use npx, replace
-`bun src/index.js` with `npx jsmdcui`.
+### Usage table
+
+- The command table below uses the cloned-source form. 
+- If you use npx, replace `bun src/index.js` with `npx jsmdcui`
 
 | Command | Result |
 | --- | --- |
 | `bun src/index.js app.md` | Render `app.md` as a read-only terminal UI and write five generated files beside it. |
+| `bun src/index.js --check app.md` | Check heading and fenced-block IDs for collisions, print line-by-line details, and exit. |
 | `bun src/index.js --edit app.md` | Open `app.md` as editable UTF-8 source, overriding automatic Markdown UI detection. |
 | `bun src/index.js --cat app.md` | Render the terminal version to stdout, write five generated files beside it, and exit. |
 | `bun src/index.js --testapp.md` | Write the bundled `testapp.md` source to stdout and exit. |
-| `bun src/index.js --demo` | Outputs & overwrites `./testapp.md`, opens it in the terminal UI, and writes 5 generated files beside it. |
+| `bun src/index.js --export-readme` | Write or overwrite `./README.md` with the bundled README source and exit. |
+| `bun src/index.js --demo` | Use local `testapp.md` when present, otherwise write the bundled demo; open it in the terminal UI and write five generated files beside it. |
+| `bun src/index.js --demo-select` | Use local `select.md` when present, otherwise write the bundled selector demo; open it in the terminal UI and write five generated files beside it. |
+| `bun src/index.js --demo-imgtool` | Use local `image-processor.md` when present, otherwise write the bundled Bun.Image processor; open it in the terminal UI and write five generated files beside it. |
+| `bun src/index.js --demo-imgtool-zh` | Use local `image-processor.zh-TW.md` when present, otherwise write the bundled Traditional Chinese Bun.Image processor; open it in the terminal UI and write five generated files beside it. |
 | `bun src/index.js --allow-url URL.md` | Download HTTP(S) Markdown to the current directory, write 5 generated files, and allow its embedded code to run. Only use trusted URLs. |
-| `bun src/index.js --wui` | Use local `testapp.md` when present, otherwise use the bundled demo; write five generated files in the current directory, then print and serve a random URL. |
+| `bun src/index.js --wui` | Use local `testapp.md` when present, otherwise write the bundled demo; write five generated files in the current directory, then print and serve a random URL. |
 | `bun src/index.js --wui app.md` | Write five generated files beside `app.md`, then print and serve a random URL. |
 | `PORT=8080 bun src/index.js --wui app.md` | Start the browser UI on another port. |
 | `bun src/index.js` | Open the normal terminal editor with an empty buffer. |
@@ -96,10 +150,19 @@ options.
 Create `app.md`:
 
 ````md
-# My app
+## My app
 
 - [Say hello](javascript:sayHello())
 - [Get server time](javascript:showServerTime())
+- [Update text box](javascript:updateText())
+- [Show selected](javascript:alert(JSON.stringify($('#my-app').val())))
+- [x] task1
+- [x] task2
+- [ ] unselected task
+
+```text#myid.myclass
+Editable in both TUI and WUI
+```
 
 ```js front
 export function sayHello() {
@@ -111,6 +174,10 @@ export async function showServerTime() {
   const time = await rpc.getServerTime();
   alert(time);
 }
+
+export function updateText() {
+  $('#myid').val($('.myclass').val() + ' ✓');
+}
 ```
 
 ```js back
@@ -127,12 +194,149 @@ bun src/index.js app.md
 bun src/index.js --wui app.md
 ```
 
+- The resulting App UI is shown at the beginning of this README.md
+- Run this demo app directly by:
+  * bun src/index.js README.md
+  * If you didn't clone the repo, use --export-readme to write README.md to the current folder
+
+### Text blocks
+
+Both `text` and `textarea` fenced blocks define editable text fields:
+
+````md
+```text#message.note
+Initial value
+```
+````
+
+A fenced-block declaration must include a tag. Its supported identity syntax is
+`tag`, optionally followed by `#id` and one or more `.class` names, for
+example `text#message.note` or `textarea#notes.readonly`. Tags, IDs, and class
+names must begin with an ASCII letter or underscore; their remaining
+characters may also include digits, `_`, `-`, and `:`. Declarations such as
+`#message` and `#message.note` have no tag and are therefore not recognized as
+selectable fenced blocks.
+
+The currently supported fenced-block tags are only `text` and `textarea` so
+the same control works consistently in both the TUI and WUI. Selector queries
+may omit the tag or classes after a valid declaration, so all of
+`$('text#message.note')`, `$('text#message')`, `$('#message.note')`, and
+`$('#message')` can select the example above.
+
+The same Markdown works in both interfaces. In the browser WUI it becomes a
+native `<textarea>` with the declared ID and classes. Long text wraps
+automatically, and the field height is recalculated when the user types, the
+window is resized, or frontend code calls `.val(value)`.
+
+In the terminal TUI, only content after the protected `│ ` or `| ` prefix can
+be edited. The frame prefix cannot be deleted, Enter cannot insert a newline,
+Delete at the end of a row cannot join the next row, and multiline paste is
+blocked. Activate the lower-left frame corner to add a row. Activate the
+upper-left frame corner to remove the trailing row only when it is empty;
+non-empty content is never removed.
+
+### Heading task lists and selector API
+
+Headings can act as form-group selectors. jsmdcui uses the IDs generated by
+`Bun.markdown.html(..., { headings: { ids: true } })`; for example,
+`## Select Color` becomes `#select-color`. A heading selection reads the first
+task list directly following that heading and stops at the next heading. Nested
+task items are not included in the outer list's value.
+
+Heading IDs share the same selector namespace as all explicitly named fenced
+blocks, not only `text` and `textarea`, so avoid name collisions between them.
+For example, `## Write Status` generates `#write-status` and must not be used
+together with a block such as `text#write-status` or
+`textarea#write-status`.
+Otherwise, `$('#write-status')` may select the heading instead of the block and
+updates can appear to do nothing. Rename either declaration so every
+selectable ID is unique.
+
+Duplicate source headings are also treated as collisions when they generate
+the same base ID. Although Bun would automatically rename later headings with
+suffixes such as `-1` and `-2`, those implicit selector names are not visible
+in the Markdown source and should not be relied on. Give each heading a name
+that produces a unique ID before rendering.
+
+Run `bun src/index.js --check app.md` (or `jsmdcui --check app.md`) to
+check these IDs without opening either UI or writing generated files. The
+command prints each collision with its source type, line number, and original
+declaration, then exits immediately. Its exit status is `0` when all IDs are
+unique, `1` when collisions are found, and `2` for invalid arguments or read
+errors.
+
+If the heading ID begins with `select`, `.val()` behaves like a single select:
+it returns the first checked item or `null`. Other heading IDs behave like a
+multiple select and return all checked items as an array, or `[]` when none are
+checked.
+
+Heading values contain the complete visible label, including any explanatory
+text. When interpreting a selection, prefer `value.includes(...)` (or another
+deliberate prefix/token parser) unless labels are guaranteed to be exact,
+stable identifiers. For example, `yes（flip vertically）` should not be tested
+with `value === "yes"`.
+
+````md
+## Select Color
+
+- [ ] Red
+- [x] Green
+- [ ] Blue
+
+## Features
+
+- [x] Search
+- [ ] Notifications
+- [x] Offline mode
+
+```js front
+export function showValues() {
+  alert(JSON.stringify({
+    color: $('#select-color').val(),
+    features: $('#features').val(),
+  }));
+}
+```
+````
+
+The same getter works in TUI and WUI:
+
+```js
+$('#select-color').val() // "Green"
+$('#features').val()     // ["Search", "Offline mode"]
+```
+
+The bundled `select.md` is a multilevel runnable example. Use `--demo-select`
+to write it into the current directory when missing and open it in the TUI, or
+open it explicitly in either interface:
+
+```sh
+bun src/index.js --demo-select
+bun src/index.js select.md
+bun src/index.js --wui select.md
+```
+
+The available selector methods are:
+
+| Method | TUI | WUI |
+| --- | --- | --- |
+| `.val()` | Read text blocks or heading task-list values. | Read textareas/controls or heading task-list values. |
+| `.val(value)` | Replace text-block contents and resize multiline values. | Set textarea/control values and resize textareas. |
+| `.html()` | Return a selected heading's inner HTML. | Return any successfully selected DOM element's `innerHTML`. |
+| `.line()` | Return a heading's current 1-based TUI row, or `0` if missing. | Not available. |
+
+TUI heading rows are recalculated after text-block rows are added, removed, or
+replaced with multiline `.val(value)` content.
+
 The three UI building blocks are:
 
 - Regular Markdown provides headings, text, lists, task checkboxes, code, and
   links.
 - A `js front` block contains UI code. Exported functions can use
   `alert`, `confirm`, `prompt`, and the generated `rpc` client.
+- A front module may export `async function onMdcuiExit({ reason, path, $ })`.
+  The terminal UI awaits it before closing an `mdcui` buffer. Modified
+  `mdcui` buffers close without a save prompt.
 - A `js back` block exports trusted backend functions. In the browser WUI,
   `rpc` publishes only exported functions whose exported names do not start
   with `_`. Call a published function from the front end with
@@ -149,6 +353,22 @@ Use a `javascript:` Markdown link to run front-end code:
 [Button label](javascript:exportedFunction())
 ```
 
+Use `onMdcuiExit` when a terminal Markdown app needs to submit or otherwise
+process edited fields before it closes:
+
+```js
+export async function onMdcuiExit({ reason, path, $ }) {
+  await rpc.saveDraft({
+    reason,
+    path,
+    message: $('#message').val(),
+  });
+}
+```
+
+The callback is optional, may be asynchronous, and is called at most once for
+each mdcui buffer.
+
 The front and back code blocks are extracted and are not shown in the rendered
 UI. In the terminal, `rpc` calls the generated backend module directly. In the
 browser, it sends the call to the relative `rpc` endpoint under the printed
@@ -156,14 +376,15 @@ UUID URL (`/<uuid>/rpc`).
 
 ## Terminal interaction
 
-Markdown files automatically use `mdcui` mode. The rendered buffer is
-read-only, but navigation, selection, search, and copy remain available.
+Markdown files automatically use `mdcui` mode. Most rendered content remains
+protected, while `text` block content rows can be edited. Navigation,
+selection, search, and copy remain available.
 
 | Input | Result |
 | --- | --- |
 | Arrow keys, `Home`, `End`, `PageUp`, `PageDown` | Move through the rendered UI. |
-| `Enter` or `Space` | Activate the cell under the cursor. Put the cursor on a `javascript:` link to run it. |
-| Left click | Move to and activate the clicked cell. A `javascript:` link runs immediately. |
+| `Enter` or `Space` | Activate the cell under the cursor. Put the cursor on a `javascript:` link to run it, or on or to the right of `☐` or `☒` to toggle that task. |
+| Left click | Move to and activate the clicked cell. A `javascript:` link runs immediately; clicking on or to the right of `☐` or `☒` toggles that task. |
 | Mouse wheel | Scroll three rows at a time. |
 | `Shift` + arrow keys | Select rendered text. |
 | `Ctrl-C` | Copy the selection, or the current line when nothing is selected. |
@@ -181,9 +402,10 @@ normal links in the browser.
 
 The WUI uses normal browser mouse and keyboard behavior. Clicking a
 `javascript:` link calls its front-end function, regular links navigate
-normally, and task checkboxes can be toggled. `alert`, `confirm`, and `prompt`
-use the browser's built-in dialogs. Checkbox changes exist only in the current
-page: refreshing does not preserve them and does not update the Markdown file.
+normally, and task checkboxes can be toggled by clicking either the checkbox or
+its associated text. `alert`, `confirm`, and `prompt` use the browser's built-in
+dialogs. Checkbox changes exist only in the current page: refreshing does not
+preserve them and does not update the Markdown file.
 
 The WUI uses port `3000` by default and accepts connections through the
 machine's available network interfaces. The printed `localhost` URL is for the
@@ -209,6 +431,26 @@ app.md-server.js
 They are regenerated from `app.md`, so edit the Markdown source rather than the
 generated files. The source directory must be writable.
 
+### Generated heading sections
+
+WUI output wraps each h1-h6 and its content in a hierarchical `<section>`.
+Lower-level headings create nested sections; the next equal or higher-level
+heading closes the applicable sections. Content before the first heading stays
+outside all generated sections.
+
+```html
+<section>
+  <h1 id="chapter">Chapter</h1>
+  <section>
+    <h2 id="topic">Topic</h2>
+  </section>
+</section>
+```
+
+This structure provides stable boundaries for CSS, DOM queries, and heading
+task-list values. Heading-like text inside comments, scripts, styles, code,
+textareas, and templates is protected and does not create sections.
+
 ## Security
 
 A Markdown UI is an executable application, not a passive document. Starting a

package/runtime/syntax/markdown.yaml

@@ -47,3 +47,15 @@ rules:
         start: "`"
         end: "`"
         rules: []
+
+
+# keywords
+# javascript alert confirm prompt rpc 
+# front back 
+# console log error JSON stringify parse
+# async await Promise 
+# textarea text password search 
+# email url tel number range color
+# date time datetime-local month week 
+# checkbox radio file hidden image button submit reset
+

package/select.md

@@ -0,0 +1,61 @@
+# Select and Task List Demo
+
+Use `Enter` or `Space` to toggle a task item in the TUI, then activate these
+links to read the values under headings at different levels.
+
+- [Read primary color (h2 single value)](javascript:showHeadingValue('select-primary-color'))
+- [Read enabled features (h3 array)](javascript:showHeadingValue('enabled-features'))
+- [Read log level (h4 single value)](javascript:showHeadingValue('select-log-level'))
+- [Read permissions (h2 array)](javascript:showHeadingValue('permissions'))
+- [Read every group](javascript:showAllHeadingValues())
+
+## Select Primary Color
+
+- [ ] Red
+- [x] Green
+  - [x] Nested green detail (ignored)
+  - [ ] Another nested detail (ignored)
+- [x] Blue (ignored because select returns the first checked value)
+
+### Enabled Features
+
+- [x] Search
+- [ ] Notifications
+  - [x] Nested notification option (ignored)
+- [x] Offline mode
+- [x] Sync
+
+#### Select Log Level
+
+- [ ] Debug
+- [x] Info
+- [ ] Warning
+- [ ] Error
+
+## Permissions
+
+- [x] Read
+- [x] Write
+  - [x] Write temporary files (ignored)
+  - [ ] Write system files (ignored)
+- [ ] Execute
+- [x] Share
+
+```js front
+export function showHeadingValue(id)
+{
+  const value = $('#'+id).val();
+  alert(id+': '+JSON.stringify(value));
+}
+
+export function showAllHeadingValues()
+{
+  const values = {
+    primaryColor: $('#select-primary-color').val(),
+    enabledFeatures: $('#enabled-features').val(),
+    logLevel: $('#select-log-level').val(),
+    permissions: $('#permissions').val(),
+  };
+  alert(JSON.stringify(values, null, 2));
+}
+```

package/single-exe/packAssets.sh

@@ -4,4 +4,4 @@ sd=$(dirname "$0")
 
 cd "$sd"/..
 
-tar -cvf single-exe/assets.tar runtime README.md CHANGELOG.md src/cui/server.mjs src/cui/rpc.mjs testapp.md
+tar -cvf single-exe/assets.tar runtime README.md CHANGELOG.md src/cui/server.mjs src/cui/rpc.mjs testapp.md select.md image-processor.md image-processor.zh-TW.md

package/src/config/defaults.js

@@ -38,7 +38,7 @@ export const DEFAULT_COMMON_SETTINGS = {
   scrollspeed: 2,
   showchars: "",
   smartpaste: true,
-  softwrap: false,
+  softwrap: true,
   splitbottom: true,
   splitright: true,
   statusformatl: "$(filename) $(modified)$(overwrite)($(line),$(col)) $(status.paste)| ft:$(opt:filetype) | $(opt:fileformat) | $(opt:encoding)",

package/src/cui/id-collision.mjs

@@ -0,0 +1,151 @@
+function markdownHeadingDeclarations(markdown) {
+  const lines = String(markdown).split(/\r?\n/);
+  const declarations = [];
+  let fence = null;
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    const fenceMatch = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      const marker = fenceMatch[1][0];
+      const length = fenceMatch[1].length;
+      if (!fence) fence = { marker, length };
+      else if (marker === fence.marker && length >= fence.length) fence = null;
+      continue;
+    }
+    if (fence) continue;
+
+    const atx = line.match(/^ {0,3}(#{1,6})(?:[ \t]+(.*?)\s*#*\s*|[ \t]*)$/);
+    if (atx) {
+      declarations.push({
+        line: index + 1,
+        source: line.trim(),
+        markdown: line,
+      });
+      continue;
+    }
+
+    if (index + 1 < lines.length && line.trim() && /^ {0,3}(?:=+|-+)\s*$/.test(lines[index + 1])) {
+      declarations.push({
+        line: index + 1,
+        source: `${line.trim()} / ${lines[index + 1].trim()}`,
+        markdown: `${line}\n${lines[index + 1]}`,
+      });
+      index++;
+    }
+  }
+
+  if (!declarations.length) return [];
+  return declarations.map((item) => {
+    // Render headings independently so Bun cannot hide a source-level
+    // collision by suffixing later duplicates as "-1", "-2", and so on.
+    const html = String(Bun.markdown.html(item.markdown, { headings: { ids: true } }));
+    const id = html.match(/<h[1-6]\b[^>]*\bid="([^"]*)"[^>]*>/i)?.[1] ?? "";
+    return {
+      id,
+      kind: "heading",
+      line: item.line,
+      source: item.source,
+    };
+  }).filter((item) => item.id);
+}
+
+function fencedBlockDeclarations(markdown) {
+  const lines = String(markdown).split(/\r?\n/);
+  const declarations = [];
+  let fence = null;
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    if (!fence) {
+      const opening = line.match(/^ {0,3}(`{3,}|~{3,})\s*(\S+)?\s*$/);
+      if (!opening) continue;
+      fence = { marker: opening[1][0], length: opening[1].length };
+      const identity = String(opening[2] ?? "").match(/^([A-Za-z_][\w:-]*)(?:#([A-Za-z_][\w:-]*))?(?:\.[A-Za-z_][\w:-]*)*$/);
+      if (identity?.[2]) {
+        declarations.push({
+          id: identity[2],
+          kind: `${identity[1]} fenced block`,
+          line: index + 1,
+          source: line.trim(),
+        });
+      }
+      continue;
+    }
+
+    const closing = line.match(/^ {0,3}(`{3,}|~{3,})\s*$/);
+    if (closing && closing[1][0] === fence.marker && closing[1].length >= fence.length)
+      fence = null;
+  }
+
+  return declarations;
+}
+
+export function checkMarkdownIdCollisions(markdown) {
+  const declarations = [
+    ...markdownHeadingDeclarations(markdown),
+    ...fencedBlockDeclarations(markdown),
+  ].sort((a, b) => a.line - b.line);
+  const byId = new Map();
+  for (const declaration of declarations) {
+    if (!byId.has(declaration.id)) byId.set(declaration.id, []);
+    byId.get(declaration.id).push(declaration);
+  }
+  const collisions = [...byId.entries()]
+    .filter(([, items]) => items.length > 1)
+    .map(([id, items]) => ({ id, declarations: items }));
+  return { declarations, collisions };
+}
+
+function inlineCode(value) {
+  const text = String(value);
+  const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map((match) => match[0].length));
+  const delimiter = "`".repeat(longest + 1);
+  const padding = text.startsWith("`") || text.endsWith("`") ? " " : "";
+  return `${delimiter}${padding}${text}${padding}${delimiter}`;
+}
+
+export function formatMarkdownIdCheck(path, result) {
+  const headings = result.declarations.filter((item) => item.kind === "heading").length;
+  const fencedBlocks = result.declarations.length - headings;
+  const lines = [
+    "# Markdown UI ID Check",
+    "",
+    `- File: ${inlineCode(path)}`,
+    `- Selectable IDs: **${result.declarations.length}**`,
+    `  * Headings: **${headings}**`,
+    `  * Fenced blocks: **${fencedBlocks}**`,
+  ];
+
+  if (!result.collisions.length) {
+    lines.push("", "## No ID collisions found");
+    return lines.join("\n");
+  }
+
+  lines.push("", `## FAIL — Found ${result.collisions.length} colliding ID(s)`);
+  for (const collision of result.collisions) {
+    lines.push("", `### ID ${inlineCode(`#${collision.id}`)}`);
+    lines.push("", `- Declarations: **${collision.declarations.length}**`);
+    for (const declaration of collision.declarations) {
+      lines.push(`  * Line **${declaration.line}**`);
+      lines.push(`    - Type: ${declaration.kind}`);
+      lines.push(`    - Source: ${inlineCode(declaration.source)}`);
+    }
+  }
+  lines.push("", "## Suggested fix", "", "- Rename the heading or fenced block so every selectable ID is unique.");
+  return lines.join("\n");
+}
+
+function statusBanner(label, color, fallbackColor) {
+  const foreground = Bun.color?.(color, "ansi-16m") || fallbackColor;
+  return `${foreground}\x1b[1m${label}\x1b[0m\n${foreground}\x1b[2m${"═".repeat(label.length)}\x1b[0m\n`;
+}
+
+export function formatMarkdownIdCheckAnsi(path, result) {
+  let output = String(Bun.markdown.ansi(formatMarkdownIdCheck(path, result)));
+  if (!output.endsWith("\n")) output += "\n";
+  output += "\n" + (result.collisions.length
+    ? statusBanner("FAILED", "#ff3030", "\x1b[31m")
+    : statusBanner("PASSED", "#00d75f", "\x1b[32m"));
+  return output;
+}