comark-ui 0.7.1 → 0.7.4

package/dist/{editor-CNivEuMH.d.mts → editor-KD97dL_1.d.mts}

@@ -1,5 +1,5 @@
 import { ComarkPlugin } from "comark";
-import { AnyExtension, Extension, JSONContent, Node } from "@tiptap/core";
+import { AnyExtension, Extension, JSONContent, Mark, Node } from "@tiptap/core";
 import { StarterKitOptions } from "@tiptap/starter-kit";
 import { EditorState, Plugin, PluginKey, Transaction } from "@tiptap/pm/state";
 import { DecorationSet } from "@tiptap/pm/view";
@@ -21,9 +21,27 @@ declare const ComarkSlot: Node<any, any>;
 declare const ComarkInline: Node<any, any>;
 /** An HTML comment between blocks. */
 declare const ComarkComment: Node<any, any>;
+/** A footnote reference, `[^label]`. */
+declare const FootnoteReference: Node<any, any>;
+/** A note written where it applies, `^[text]`. */
+declare const InlineFootnote: Node<any, any>;
+/** A footnote's text, `[^label]: text`, with the blocks indented under it. */
+declare const FootnoteDefinition: Node<any, any>;
+/** A definition list, `Term` then `: Definition`. */
+declare const DefinitionList: Node<any, any>;
+declare const DefinitionTerm: Node<any, any>;
+declare const DefinitionDescription: Node<any, any>;
+/** CriticMarkup's suggested insertion, `{++text++}`. */
+declare const CriticInsertion: Mark<any, any>;
+/** CriticMarkup's suggested deletion, `{--text--}`. */
+declare const CriticDeletion: Mark<any, any>;
+/** CriticMarkup's highlight, `{==text==}`. */
+declare const CriticHighlight: Mark<any, any>;
+/** CriticMarkup's comment, `{>>text<<}`. */
+declare const CriticComment: Node<any, any>;
 /**
  * The schema `fromMarkdown` and `toMarkdown` read and write: StarterKit's nodes and marks, task lists, inline images,
- * tables, and Comark's components, slots, and comments. It needs no DOM, so a server can load it to convert a document
+ * tables, footnotes, definition lists, CriticMarkup, and Comark's components, slots, and comments. It needs no DOM, so a server can load it to convert a document
  * for a collaborative room.
  */
 declare const ComarkKit: Extension<ComarkKitOptions, any>;
@@ -128,4 +146,4 @@ interface EditorCodecOptions {
 }
 declare function createEditorCodec(options?: EditorCodecOptions): EditorCodec;
 //#endregion
-export { ComarkSlot as S, ComarkComment as _, Upload as a, ComarkKit as b, startUploads as c, EditorDocument as d, MarkdownCheck as f, ComarkBlock as g, toMarkdown as h, PendingUpload as i, uploadKey as l, fromMarkdown as m, EditorCodecOptions as n, UploadOptions as o, checkMarkdown as p, createEditorCodec as r, findUpload as s, EditorCodec as t, uploadPlugin as u, ComarkImage as v, ComarkKitOptions as x, ComarkInline as y };
+export { FootnoteDefinition as A, CriticComment as C, DefinitionDescription as D, CriticInsertion as E, InlineFootnote as M, DefinitionList as O, ComarkSlot as S, CriticHighlight as T, ComarkComment as _, Upload as a, ComarkKit as b, startUploads as c, EditorDocument as d, MarkdownCheck as f, ComarkBlock as g, toMarkdown as h, PendingUpload as i, FootnoteReference as j, DefinitionTerm as k, uploadKey as l, fromMarkdown as m, EditorCodecOptions as n, UploadOptions as o, checkMarkdown as p, createEditorCodec as r, findUpload as s, EditorCodec as t, uploadPlugin as u, ComarkImage as v, CriticDeletion as w, ComarkKitOptions as x, ComarkInline as y };

package/dist/editor-vue.d.mts

@@ -1,4 +1,4 @@
-import { x as ComarkKitOptions } from "./editor-CNivEuMH.mjs";
+import { x as ComarkKitOptions } from "./editor-KD97dL_1.mjs";
 import { ComarkPlugin } from "comark";
 import { AnyExtension } from "@tiptap/core";
 import { Editor } from "@tiptap/vue-3";

package/dist/editor-vue.mjs

@@ -1,4 +1,4 @@
-import { c as fromMarkdown, l as toMarkdown, m as ComarkKit, s as checkMarkdown } from "./editor-BAdok66p.mjs";
+import { c as fromMarkdown, l as toMarkdown, m as ComarkKit, s as checkMarkdown } from "./editor-DmxNPK7K.mjs";
 import { Editor, EditorContent } from "@tiptap/vue-3";
 import { defineComponent, h, onScopeDispose, ref, shallowRef, watch } from "vue";
 //#region src/editor-vue.ts

package/dist/editor.d.mts

@@ -1,2 +1,2 @@
-import { S as ComarkSlot, _ as ComarkComment, a as Upload, b as ComarkKit, c as startUploads, d as EditorDocument, f as MarkdownCheck, g as ComarkBlock, h as toMarkdown, i as PendingUpload, l as uploadKey, m as fromMarkdown, n as EditorCodecOptions, o as UploadOptions, p as checkMarkdown, r as createEditorCodec, s as findUpload, t as EditorCodec, u as uploadPlugin, v as ComarkImage, x as ComarkKitOptions, y as ComarkInline } from "./editor-CNivEuMH.mjs";
-export { ComarkBlock, ComarkComment, ComarkImage, ComarkInline, ComarkKit, type ComarkKitOptions, ComarkSlot, type EditorCodec, type EditorCodecOptions, type EditorDocument, type MarkdownCheck, type PendingUpload, Upload, type UploadOptions, checkMarkdown, createEditorCodec, findUpload, fromMarkdown, startUploads, toMarkdown, uploadKey, uploadPlugin };
+import { A as FootnoteDefinition, C as CriticComment, D as DefinitionDescription, E as CriticInsertion, M as InlineFootnote, O as DefinitionList, S as ComarkSlot, T as CriticHighlight, _ as ComarkComment, a as Upload, b as ComarkKit, c as startUploads, d as EditorDocument, f as MarkdownCheck, g as ComarkBlock, h as toMarkdown, i as PendingUpload, j as FootnoteReference, k as DefinitionTerm, l as uploadKey, m as fromMarkdown, n as EditorCodecOptions, o as UploadOptions, p as checkMarkdown, r as createEditorCodec, s as findUpload, t as EditorCodec, u as uploadPlugin, v as ComarkImage, w as CriticDeletion, x as ComarkKitOptions, y as ComarkInline } from "./editor-KD97dL_1.mjs";
+export { ComarkBlock, ComarkComment, ComarkImage, ComarkInline, ComarkKit, type ComarkKitOptions, ComarkSlot, CriticComment, CriticDeletion, CriticHighlight, CriticInsertion, DefinitionDescription, DefinitionList, DefinitionTerm, type EditorCodec, type EditorCodecOptions, type EditorDocument, FootnoteDefinition, FootnoteReference, InlineFootnote, type MarkdownCheck, type PendingUpload, Upload, type UploadOptions, checkMarkdown, createEditorCodec, findUpload, fromMarkdown, startUploads, toMarkdown, uploadKey, uploadPlugin };

package/dist/editor.mjs

@@ -1 +1 @@
-export { u as ComarkBlock, d as ComarkComment, f as ComarkImage, p as ComarkInline, m as ComarkKit, h as ComarkSlot, n as Upload, s as checkMarkdown, t as createEditorCodec, r as findUpload, c as fromMarkdown, i as startUploads, l as toMarkdown, a as uploadKey, o as uploadPlugin } from "./editor-BAdok66p.mjs";
+export { u as ComarkBlock, d as ComarkComment, f as ComarkImage, p as ComarkInline, m as ComarkKit, h as ComarkSlot, g as CriticComment, _ as CriticDeletion, v as CriticHighlight, y as CriticInsertion, b as DefinitionDescription, x as DefinitionList, S as DefinitionTerm, C as FootnoteDefinition, w as FootnoteReference, T as InlineFootnote, n as Upload, s as checkMarkdown, t as createEditorCodec, r as findUpload, c as fromMarkdown, i as startUploads, l as toMarkdown, a as uploadKey, o as uploadPlugin } from "./editor-DmxNPK7K.mjs";

package/dist/html.d.mts

@@ -1,6 +1,12 @@
-import { a as criticCss, n as Preset, r as PresetOptions } from "./index-B0YvApci.mjs";
+import { a as criticCss, n as Preset, r as PresetOptions } from "./index-BUDHsvnm.mjs";
 import { NodeHandler } from "comark";
 //#region src/html.d.ts
+/**
+ * The text of the inline `<script>` that runs the Mermaid diagrams' Copy image and Copy source buttons. It's the same on
+ * every render and changes only between versions, so a page with a strict Content Security Policy can allow it by its
+ * hash without rendering a document first.
+ */
+export declare const mermaidScript: string;
 /** Every plugin for `@comark/html`, with the `components` to render them. */
 declare const _default: (options?: PresetOptions) => Preset<NodeHandler>;
 //#endregion

package/dist/html.mjs

@@ -1,6 +1,7 @@
-import { t as typesetCss } from "./typeset-css-DPB0S1bV.mjs";
-import { n as preset, t as criticCss } from "./src-DROB05U6.mjs";
-import { mermaidCss } from "./client.mjs";
+import { t as typesetCss } from "./typeset-css-5aJ7cSmh.mjs";
+import { n as preset, t as criticCss } from "./src-PkmYCSNu.mjs";
+import { a as start, n as mermaidBar, r as mermaidCss } from "./client-Bjd6VcGQ.mjs";
+import { escapeHtml } from "comark/utils";
 import * as annotate from "comark-annotate/html";
 import * as badge from "comark-badge/html";
 import * as cards from "comark-cards/html";
@@ -11,6 +12,7 @@ import * as chips from "comark-chips/html";
 import * as code from "comark-code/html";
 import * as codeNotes from "comark-code-notes/html";
 import * as colors from "comark-colors/html";
+import * as comments from "comark-comments/html";
 import * as details from "comark-details/html";
 import * as diagrams from "comark-diagrams/html";
 import * as diff from "comark-diff/html";
@@ -38,14 +40,31 @@ import * as tests from "comark-tests/html";
 import * as zoom from "comark-zoom/html";
 //#region src/html.ts
 const styled = /* @__PURE__ */ new WeakSet();
-const mermaid = {
+/**
+* The text of the inline `<script>` that runs the Mermaid diagrams' Copy image and Copy source buttons. It's the same on
+* every render and changes only between versions, so a page with a strict Content Security Policy can allow it by its
+* hash without rendering a document first.
+*/
+const mermaidScript = `(${start.toString()})()`;
+const attr = (value) => escapeHtml(value, { "\"": "&quot;" });
+/**
+* Wraps Pele's card in `.cmm` with the bar of buttons and the source they copy. The wrapper is a wide block with the
+* diagram's own width, so a page that gives wide blocks room shows a long flowchart at its size rather than shrinking
+* its labels to fit the column. A drawn diagram zooms with comark-zoom unless the preset turns zoom off.
+*/
+const mermaid = (zooms) => ({
 	default: pele,
 	components: { pele: ((node, state) => {
-		const styles = styled.has(state.context) ? "" : `<style data-comark-mermaid>${mermaidCss}</style>`;
+		const first = !styled.has(state.context);
 		styled.add(state.context);
-		return styles + Pele(node);
+		const card = Pele(node);
+		const source = node[1].content;
+		const width = /^<div[^>]*><svg[^>]* width="([\d.]+)"/.exec(card)?.[1];
+		const wide = width ? ` data-wide style="--cmm-svg:${Math.ceil(Number(width))}px"` : "";
+		const zoomed = zooms && width ? card.replace(/^<div/, "<div data-zoom tabindex=\"0\"") : card;
+		return (first ? `<style data-comark-mermaid>${mermaidCss}</style>` : "") + `<div class="cmm"${wide} data-source="${attr(source)}">${zoomed}<div class="cmm-bar">${mermaidBar()}</div>${first ? `<script>${mermaidScript}<\/script>` : ""}${zooms && width ? zoom.runtime(state) : ""}</div>`;
 	}) }
-};
+});
 const typeset = () => `<style data-comark-typeset>${typesetCss}</style>`;
 /** Every plugin for `@comark/html`, with the `components` to render them. */
 var html_default = (options) => preset({
@@ -59,6 +78,7 @@ var html_default = (options) => preset({
 	code,
 	codeNotes,
 	colors,
+	comments,
 	details,
 	diagrams,
 	diff,
@@ -72,7 +92,7 @@ var html_default = (options) => preset({
 	mark,
 	math,
 	media,
-	mermaid,
+	mermaid: mermaid(options?.zoom !== false),
 	metrics,
 	outline,
 	properties,
@@ -87,4 +107,4 @@ var html_default = (options) => preset({
 	zoom
 }, options);
 //#endregion
-export { criticCss, html_default as default };
+export { criticCss, html_default as default, mermaidScript };

package/dist/{index-B0YvApci.d.mts → index-BUDHsvnm.d.mts}

@@ -12,6 +12,7 @@ import { CastOptions } from "comark-cast";
 import { ChartsOptions } from "comark-charts";
 import { ChipsOptions } from "comark-chips";
 import { CodeOptions } from "comark-code";
+import { CommentsOptions } from "comark-comments";
 import { DetailsOptions } from "comark-details";
 import { DiagramsOptions } from "comark-diagrams";
 import { FileTreeOptions } from "comark-file-tree";
@@ -19,6 +20,7 @@ import { CalloutsOptions, ReferencesOptions } from "comark-github";
 import { AnchorsOptions, ExternalOptions } from "comark-links";
 import { MathOptions } from "comark-mathml";
 import { MediaOptions } from "comark-media";
+import { OutlineOptions } from "comark-outline";
 import { PeleConfig } from "comark-pele";
 import { PropertiesOptions } from "comark-properties";
 import { QuizOptions } from "comark-quiz";
@@ -53,6 +55,11 @@ type PresetOptions = {
   /** Pass `{ download: false }` when parsing in a browser, which may not download another site's images. */
   chips?: ChipsOptions | boolean;
   colors?: boolean;
+  /**
+   * HTML only: Vue, React, and Svelte have no comments components. `{ mark: "pen" }` draws suggestions with a
+   * hand-drawn pen unless one sets its own `mark`.
+   */
+  comments?: CommentsOptions | boolean;
   /** Sends each diagram's source to `https://kroki.io` unless you pass your own `server`, or `{ draw: false }`. */
   diagrams?: DiagramsOptions | boolean;
   /** Draws `mermaid` fences with comark-pele, on the server and offline. */
@@ -94,7 +101,8 @@ type PresetOptions = {
   steps?: boolean;
   readingTime?: ReadingTimeOptions | boolean;
   tabs?: TabsOptions | boolean;
-  outline?: boolean;
+  /** `{ rail: true }` adds a side outline beside the text of every document with two headings or more. Off by default. */
+  outline?: OutlineOptions | boolean;
   xref?: XrefOptions | boolean;
   /** Reads no JUnit reports unless you pass `{ root }` or `{ read }`; inline reports render either way. */
   tests?: TestsOptions | boolean;
@@ -120,6 +128,7 @@ type Renderer<C> = {
   charts: Part<C, ChartsOptions>;
   chips: Part<C, ChipsOptions>;
   colors: Part<C>;
+  comments?: Part<C, CommentsOptions>;
   diagrams: Part<C, DiagramsOptions>;
   mermaid: Part<C, PeleConfig>;
   diff?: Part<C>;
@@ -155,7 +164,7 @@ type Renderer<C> = {
   sources: Part<C>;
   steps: Part<C>;
   tabs: Part<C, TabsOptions>;
-  outline: Part<C>;
+  outline: Part<C, OutlineOptions>;
   tests: Part<C, TestsOptions>;
   zoom: Part<C, ZoomOptions>;
   code: Part<C, CodeOptions>;

package/dist/index.d.mts

@@ -1,3 +1,3 @@
 import { t as typesetCss } from "./typeset-css-DdOGL7WF.mjs";
-import { a as criticCss, c as typeset, i as Renderer, n as Preset, o as preset, r as PresetOptions, s as TYPESET_TAG, t as AnyPlugin } from "./index-B0YvApci.mjs";
+import { a as criticCss, c as typeset, i as Renderer, n as Preset, o as preset, r as PresetOptions, s as TYPESET_TAG, t as AnyPlugin } from "./index-BUDHsvnm.mjs";
 export { AnyPlugin, Preset, PresetOptions, Renderer, TYPESET_TAG, criticCss, preset, typeset, typesetCss };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { t as typesetCss } from "./typeset-css-DPB0S1bV.mjs";
-import { i as typeset, n as preset, r as TYPESET_TAG, t as criticCss } from "./src-DROB05U6.mjs";
+import { t as typesetCss } from "./typeset-css-5aJ7cSmh.mjs";
+import { i as typeset, n as preset, r as TYPESET_TAG, t as criticCss } from "./src-PkmYCSNu.mjs";
 export { TYPESET_TAG, criticCss, preset, typeset, typesetCss };

package/dist/react.d.mts

@@ -1,8 +1,8 @@
-import { a as criticCss, n as Preset, r as PresetOptions } from "./index-B0YvApci.mjs";
+import { a as criticCss, n as Preset, r as PresetOptions } from "./index-BUDHsvnm.mjs";
 import { ComponentType } from "react";
 //#region src/react.d.ts
 type AnyComponent = ComponentType<any>;
-/** Every plugin with components for `@comark/react`, which leaves out annotate, diff, and quiz. */
+/** Every plugin with components for `@comark/react`, which leaves out annotate, comments, diff, and quiz. */
 declare const _default: (options?: PresetOptions) => Preset<AnyComponent>;
 //#endregion
 export { type PresetOptions, criticCss, _default as default };

package/dist/react.mjs

@@ -1,7 +1,7 @@
-import { t as typesetCss } from "./typeset-css-DPB0S1bV.mjs";
-import { n as preset, t as criticCss } from "./src-DROB05U6.mjs";
-import { addMermaidStyles } from "./client.mjs";
-import { createElement } from "react";
+import { t as typesetCss } from "./typeset-css-5aJ7cSmh.mjs";
+import { n as preset, t as criticCss } from "./src-PkmYCSNu.mjs";
+import { i as startMermaid, n as mermaidBar, t as addMermaidStyles } from "./client-Bjd6VcGQ.mjs";
+import { createElement, useEffect } from "react";
 import * as badge from "comark-badge/react";
 import * as cards from "comark-cards/react";
 import * as carousel from "comark-carousel/react";
@@ -35,15 +35,29 @@ import * as tabs from "comark-tabs/react";
 import * as tests from "comark-tests/react";
 import * as zoom from "comark-zoom/react";
 //#region src/react.ts
+const Pele = createPeleComponent({
+	onRender: addMermaidStyles,
+	onError: addMermaidStyles
+});
+function Mermaid(props) {
+	useEffect(() => startMermaid(), []);
+	return createElement("div", {
+		className: "cmm",
+		"data-source": props.content
+	}, createElement(Pele, props), createElement("div", {
+		className: "cmm-bar",
+		dangerouslySetInnerHTML: { __html: mermaidBar() }
+	}));
+}
 const mermaid = {
 	default: pele,
-	components: { pele: createPeleComponent({ onRender: addMermaidStyles }) }
+	components: { pele: Mermaid }
 };
 const typeset = () => createElement("style", {
 	"data-comark-typeset": "",
 	dangerouslySetInnerHTML: { __html: typesetCss }
 });
-/** Every plugin with components for `@comark/react`, which leaves out annotate, diff, and quiz. */
+/** Every plugin with components for `@comark/react`, which leaves out annotate, comments, diff, and quiz. */
 var react_default = (options) => preset({
 	badge,
 	cards,

package/dist/skills/before-after-evidence/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: before-after-evidence
+description: Shows a visible change as two comparable screenshots, before and after, with marks measured from the source and checked in the rendered page. Use when a pull request, bug fix, or design change alters what people see, or when someone asks for before/after screenshots or visual evidence.
+license: MIT
+---
+
+# Before/after evidence
+
+A before/after is evidence when a reviewer can check every claim against the two images and nothing else. Three things make it so, and the reader can't repair any of them: two captures of the same view, marks that sit on what changed, and notes in the words the screen shows.
+
+This skill writes the document. Where it's published, and who can open it, is up to your host.
+
+## 1. Capture a comparable pair
+
+Take **after** from the branch or its preview, and **before** from a deployment or commit that still behaves the old way. Capture both with the same viewport, zoom, theme, data, scroll position, and open menus, so the change is the only difference.
+
+- Set up the state that shows the change before you capture: the long name that wrapped, the error that stayed hidden, the empty list.
+- Clip both captures to one region around the change, the same rectangle on each side. A `::compare` gives each image under half the page width, where a full-page capture's text is too small to read.
+- Pin anything that moves the layout between the two states, such as a dialog centered vertically that grows by one line, so the same element sits at the same place in both.
+
+If one side can't be captured comparably, stop and say what blocked you. A description in place of a screenshot, or one side alone, isn't before/after evidence.
+
+Done when both images exist, have the same size, and differ only where the change is.
+
+## 2. Measure every mark
+
+Marks take `x`, `y`, `w`, and `h` as percentages of the image. Measure them: an estimate drifts a few percent, and on a half-width image that's the neighbouring button.
+
+- **A page you captured:** read the element's box in the same browser, viewport, and state, minus the clip's offset. [references/measuring.md](references/measuring.md) has the snippet.
+- **A still you didn't capture**, such as a frame from a screen recording, a design export, or an image attached to a bug report: there is no DOM to ask. Measure in image pixels and divide by the image's natural width and height. Confirm each box by cropping the image to it and looking at the crop, as the same reference shows.
+
+Mark the change at its own size: the field, the label, the button. Use `red` on the before side for the problem and `green` on the after side for the fix, and leave what stayed the same unmarked. Two or three marks a side usually tell the whole story.
+
+Done when every mark has numbers you measured, and you can name the element or the pixel rectangle each came from.
+
+## 3. Write the document
+
+Start from [references/example.md](references/example.md) and keep its shape:
+
+1. One sentence: what changed, and for whom.
+2. One line of steps to reach the screen, so a reviewer can reproduce it.
+3. The `::compare`, each note a few words in the screen's own words. A value the screenshot doesn't show stays out of its note.
+4. A `::diff` of the line that caused it, only when the reader would otherwise ask.
+
+The images carry the evidence, so the text only points into them. How the work went (the checks you ran, retries, CI) goes in your report to the user, not in the document. [references/blocks.md](references/blocks.md) has the syntax of each block.
+
+Image `src` must be a URL the renderer can reach: a path next to the document, or an https URL your host gives you for the upload.
+
+## 4. Check the render
+
+1. Lint it, and fix until it reports no problems:
+
+   ```sh
+   vp dlx --package comark-linter --package comark-ui lint-comark evidence.md
+   ```
+
+   These commands use the [global Vite+ CLI](https://viteplus.dev/guide/global-cli). Without it, `pnpm dlx` takes the same arguments.
+
+2. Open the page where it will be read and take a screenshot of it. For a local screenshot-only check, copy the complete `::compare` block, including its nested screenshots and annotations, into `evidence-screenshots.md` beside `evidence.md`.
+
+   Ensure comark-annotate is a direct dependency of this workspace package. If it is only transitive, read the installed Comark UI version and add that exact version with the project's package manager: for pnpm, `pnpm add -D comark-annotate@<version>`, substituting that version. Add `-w` when installing at the workspace root. With no Comark UI packages installed, omit `@<version>`. This links the executable without fetching a different renderer release via `@latest`. Then run:
+
+   ```sh
+   vp exec comark-annotate render evidence-screenshots.md -o evidence-screenshots.html
+   ```
+
+   Without Vite+, use `pnpm exec` with the same arguments.
+
+   Open `evidence-screenshots.html` and take a screenshot of it. This CLI renders annotate, carousel, and zoom only; check any `::diff` or other blocks in the host's full Comark UI preview.
+3. Check that each mark sits on its target and each note matches what its side shows. Measure a mark that misses again, from the source, since a box moved by eye stays a guess.
+
+Done when you've looked at the rendered page and every mark lands. Name any mark or block you couldn't check in your report.

package/dist/skills/before-after-evidence/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Before/after evidence"
+  short_description: "Show a visible change with comparable, measured screenshots"

package/dist/skills/before-after-evidence/references/blocks.md

@@ -0,0 +1,54 @@
+# Blocks for before/after evidence
+
+These blocks come with `comark-ui`, or alone with `comark-annotate` and `comark-diff`. The comark-ui skill (`vp dlx skills add onmax/comark-ui`) documents every block in full.
+
+## `::compare`
+
+Two `:::screenshot` blocks inside, before then after. They're titled Before and After unless they set `title`, and their notes are numbered across both.
+
+| Prop | What it does |
+| --- | --- |
+| `title` | Names the comparison for screen readers. |
+| `mode` | `columns` (default) side by side, or `slider`: one full-width image with a divider to drag. Use `slider` when the change is small and in the same spot, such as one label. |
+
+## `:::screenshot`
+
+| Prop | What it does |
+| --- | --- |
+| `src` | Required. The image URL. |
+| `alt` | Required. What the image shows, in one phrase. |
+| `viewport` | The capture's size, like `640x420`. Set the same on both sides; a compare reports a mismatch. |
+| `href` | The page you captured, such as the preview deployment, linked by its host above the image. |
+| `title` | A heading above the image, in place of Before or After. |
+
+Other Markdown inside the block, after its annotations, becomes the caption.
+
+## `::::annotation`
+
+A direct child of a screenshot. Its content is the note, in Markdown.
+
+| Prop | What it does |
+| --- | --- |
+| `x` `y` `w` `h` | Required. The marked rectangle as percentages of the image, without `%`. |
+| `mark` | `box` (default), `circle`, `underline`, `highlight`, `bracket`, `cross`, `check`, or `none`. |
+| `color` | `red` for a problem, `green` for the fix, `amber` for a warning, `violet` (default) to point something out, `gray`, or a hex color. |
+| `side` | `top` or `bottom` moves the note into the margin with an arrow; in a side-by-side compare, `left` and `right` notes join the numbered list. |
+
+Notes without a `side` are numbered under their image, which is the clearest default in a compare.
+
+## `::diff`
+
+Two fenced blocks inside, the file before and after, starting at the same line.
+
+````md
+::diff{line=42 label="The change"}
+```tsx [src/members/InviteDialog.tsx]
+<button onClick={send}>Send invite</button>
+```
+```tsx
+<button onClick={send} disabled={invalid}>Send invite</button>
+```
+::
+````
+
+`line` is the file's line number of the first line in both blocks. Keep a diff to the few lines that caused the change; the pull request has the rest.

package/dist/skills/before-after-evidence/references/example.md

@@ -0,0 +1,37 @@
+The invite dialog now says what's wrong with an address, and waits for a valid one before it sends.
+
+Open **Settings › Members**, select **Invite**, type `maria@acme`, and press Tab.
+
+::compare{title="Invite dialog with an incomplete address"}
+:::screenshot{src="https://comark-ui.onmax.me/skill-invite-before.png" alt="Invite dialog with a red email field and no message" viewport="640x420"}
+::::annotation{x=8.3 y=42.9 w=60.6 h=12.8 color="red"}
+Only the border turns red. Nothing says what to fix.
+::::
+
+::::annotation{x=72 y=63.5 w=19.7 h=11.5 color="red"}
+**Send invite** still sends to `maria@acme`.
+::::
+:::
+
+:::screenshot{src="https://comark-ui.onmax.me/skill-invite-after.png" alt="Invite dialog with an error under the email field and a disabled Send invite button" viewport="640x420" href="https://pr-218.preview.acme.example/settings/members"}
+::::annotation{x=8.3 y=58.3 w=49 h=5.8 mark="underline" color="green"}
+"Add the domain, like maria@acme.com"
+::::
+
+::::annotation{x=72 y=71.8 w=19.7 h=11.5 color="green"}
+**Send invite** waits for a valid address.
+::::
+:::
+::
+
+::diff{line=42 label="The change"}
+```tsx [src/members/InviteDialog.tsx]
+<input id="email" aria-invalid={invalid} value={email} onChange={edit} />
+<button className="primary" onClick={send}>Send invite</button>
+```
+```tsx
+<input id="email" aria-invalid={invalid} aria-describedby="email-error" value={email} onChange={edit} />
+{invalid && <p id="email-error" className="error">Add the domain, like {suggestion}</p>}
+<button className="primary" onClick={send} disabled={invalid}>Send invite</button>
+```
+::

package/dist/skills/before-after-evidence/references/measuring.md

@@ -0,0 +1,50 @@
+# Measuring marks
+
+Every mark is `x y w h`, each a percentage of the image from 0 to 100. Measure in the same coordinates the image was captured in.
+
+## A page you captured
+
+Capture both states with one clip, then read each element's box in the same page, before anything moves:
+
+```js
+// Playwright: one clip for both sides, so the same element sits at the same place.
+const clip = { x: 56, y: 12, width: 528, height: 312 };
+await page.screenshot({ path: "after.png", clip });
+
+const box = await page.$eval("#email", (el, clip) => {
+  const r = el.getBoundingClientRect();
+  return [
+    ((r.x - clip.x) / clip.width) * 100,
+    ((r.y - clip.y) / clip.height) * 100,
+    (r.width / clip.width) * 100,
+    (r.height / clip.height) * 100,
+  ].map((v) => +v.toFixed(1));
+}, clip);
+// box is [x, y, w, h] for the annotation.
+```
+
+- Without a clip, divide by `innerWidth` and `innerHeight` and subtract nothing.
+- For a full-page capture, add `scrollX` and `scrollY` to the box and divide by `document.documentElement.scrollWidth` and `scrollHeight`.
+- An element that spans its container, such as a block paragraph, measures as wide as the container. Measure the text instead: give it `width: fit-content` while you capture, or measure a `Range` around its text.
+- If an element crosses the clip's edge, cut its box at the edge, so every value stays between 0 and 100.
+
+## A still you didn't capture
+
+A frame from a screen recording, a design export, or an image attached to an issue has no DOM. Measure in pixels:
+
+1. Read the image's natural size, such as with `magick identify frame.png` or `file frame.png`.
+2. Find the target's rectangle in pixels in an image viewer that shows the pointer's coordinates.
+3. Divide: `x = left / width * 100`, `y = top / height * 100`, `w = boxWidth / width * 100`, `h = boxHeight / height * 100`.
+4. Crop the image to that rectangle and look at the crop. It should show the target and little else:
+
+   ```sh
+   magick frame.png -crop 320x38+44+134 +repage crop.png
+   ```
+
+   With Python and Pillow, `Image.open("frame.png").crop((44, 134, 364, 172)).save("crop.png")` does the same.
+
+For a pair of video frames, take both at the same playback size and use the same crop for both, as you would clip two page captures.
+
+## In the render
+
+The rendered page is the last check. A mark that misses there has the wrong numbers: measure it again from the source.

package/dist/skills/comark-ui/SKILL.md

@@ -15,6 +15,8 @@ Prefer `comark-ui`, every plugin in one install, registered in the order they ne
 pnpm add comark @comark/html comark-ui
 ```
 
+Run the comark CLIs with the [global Vite+ CLI](https://viteplus.dev/guide/global-cli): `vp dlx` for a package the project doesn't install, `vp exec` for one it does. Without Vite+, `pnpm dlx` and `pnpm exec` take the same arguments.
+
 ```ts
 import { createHtmlRenderer } from "@comark/html";
 import comarkUi from "comark-ui/html";
@@ -43,6 +45,10 @@ Either way, the HTML renderer inlines the styles once per document, and the Vue,
 
 Problems land in `meta.issues` after `parseMarkdown`, one sentence each, and a host can refuse a document while any remain. For untrusted input, add Comark's `security` plugin with `blockedTags` such as `script`, `style`, and `iframe`; it cleans the Markdown inside blocks too.
 
+## Shape the document
+
+This skill teaches the blocks. Four sibling skills teach a whole document, what goes in it and in what order: `before-after-evidence`, `review-document`, `visual-explanation`, and `teach-lesson`. When the user asks for one of those and the skill isn't installed, suggest `vp dlx skills add onmax/comark-ui` and picking it from the list.
+
 ## Pick the blocks
 
 Read the reference for each block you use before you write it. Mix the blocks freely with ordinary Markdown, such as headings, tables, and lists.
@@ -55,10 +61,11 @@ Read the reference for each block you use before you write it. Mix the blocks fr
 | A change on screen, before and after | `::compare` | [annotate](references/annotate.md) |
 | A command's output, such as a test run or a build, as colored text | `::cast` | [cast](references/cast.md) |
 | Numbers, such as sizes, timings, before/after metrics, a trend, or a timeline | `::chart` | [charts](references/charts.md) |
-| A flow, a sequence, an architecture, or a schema as a diagram | a `d2`, `dot`, `plantuml`, `dbml`, `goat`, or `svgbob` fence | [diagrams](references/diagrams.md) |
+| A flow, a sequence, an architecture, or a schema as a diagram | a `mermaid`, `d2`, `dot`, `plantuml`, `dbml`, `goat`, or `svgbob` fence | [diagrams](references/diagrams.md) |
 | Links and `@mentions` with the site's favicon or the person's avatar | links, `@user`, `:chip` | [chips](references/chips.md) |
 | Colors, such as design tokens before and after, or a palette | a color in inline code, `::palette` | [colors](references/colors.md) |
 | A suggested change to one file, before and after | `::diff` | [diff](references/diff.md) |
+| Suggested edits and comment threads on prose, such as a copy review, each note in a card in the margin | `:suggestion`, `:comment` | [comments](references/comments.md) |
 | A video, a design file, or a live reproduction from its link | `::embed` | [embed](references/embed.md) |
 | A screen recording or a sound that a screenshot can't show | `![alt](clip.mp4)` | [media](references/media.md) |
 | A number before and after, a table of befores and afters, or progress | `:delta`, `::stats`, `:progress` | [metrics](references/metrics.md) |
@@ -134,5 +141,5 @@ Mark only what your text talks about. Each note says what changed or what is wro
 
 ## Check the result
 
-1. Lint the file: `npx lint-comark report.md`, in a project with `comark-linter` and the plugins installed, where `comark-ui` counts as every plugin. It prints one line per problem with its line, its rule, and how to fix it, and exits with 1 while any remain. Fix every one, and run it again until it exits with 0. The [lint reference](references/lint.md) covers its flags, its config file, the library, ESLint, and Vite Doctor.
+1. Lint the file: `vp exec lint-comark report.md`, in a project with `comark-linter` and the plugins installed, where `comark-ui` counts as every plugin. It prints one line per problem with its line, its rule, and how to fix it, and exits with 1 while any remain. Fix every one, and run it again until it exits with 0. The [lint reference](references/lint.md) covers its flags, its config file, the library, ESLint, and Vite Doctor.
 2. Look at the render, made as the block's reference says. Open it in a browser and take a screenshot: each mark sits on its target, each number matches its note, and each chart says what your text says. If you can't verify something, say so when you hand the document over instead of guessing.

package/dist/skills/comark-ui/references/annotate.md

@@ -53,11 +53,13 @@ For a clipped capture, `getBoundingClientRect()` and Playwright's main-frame `cl
 
 ## Preview
 
+Ensure comark-annotate is a direct dependency of the workspace package where you run the CLI. If it is only transitive, read the installed Comark UI version and add that exact version with the project's package manager: for pnpm, `pnpm add -D comark-annotate@<version>`, substituting that version. Add `-w` when installing at the workspace root. With no Comark UI packages installed, omit `@<version>`. This links the executable without fetching a different renderer release via `@latest`.
+
 ```sh
-npx comark-annotate render report.md -o report.html
+vp exec comark-annotate render report.md -o report.html
 ```
 
-`render` writes a standalone page of the screenshots and compares, and relative `src` paths resolve next to it. Without comark-linter, `npx comark-annotate check report.md` lists these blocks' problems on its own. It names each one like `screenshot "after.png", annotation 2`, counting annotations within their screenshot, and exits with 1 while any remain.
+`render` writes a standalone page of the screenshots and compares, and relative `src` paths resolve next to it. Without comark-linter, `vp exec comark-annotate check report.md` lists these blocks' problems on its own. It names each one like `screenshot "after.png", annotation 2`, counting annotations within their screenshot, and exits with 1 while any remain.
 
 ## Register
 

package/dist/skills/comark-ui/references/comments.md

@@ -0,0 +1,43 @@
+# Suggestions and comments
+
+comark-comments draws suggested edits and comments on a span of prose, each with its note in a card in the margin beside its line, as in a Google Docs or Word review. Use it to review copy or a docs page, where each change needs a reason and a comment can get a reply. For marks with no notes or margin, which a host can also accept or reject, use [critic](critic.md). For a change to code, write a `::diff`.
+
+## Syntax
+
+```md
+To :suggestion[sign in]{from="log in" by="Claude" note="The button says Sign in."}, enter your email.
+
+:suggestion[]{from="simply" by="Claude" note="“Simply” tells a stuck reader it should have been easy."} Enter the email you signed up with.
+
+The link expires after :comment[15 minutes]{#ttl by="@onmax" note="Is 15 minutes enough when email is slow?"}.
+
+:comment{reply="ttl" by="Claude" note="Keeping 15. The email has a resend button."}
+```
+
+| Write | Is |
+| --- | --- |
+| `:suggestion[new]{from="old"}` | A replacement: `old` struck, `new` inserted |
+| `:suggestion[]{from="old"}` or `:suggestion{from="old"}` | A deletion |
+| `:suggestion[new]` | An insertion |
+| `:comment[words]{note="…"}` | A comment on `words` |
+| `:comment{reply="id" note="…"}` | A reply to the comment or suggestion with `#id` |
+
+| Prop | On | What it does |
+| --- | --- | --- |
+| `from` | suggestion | The text it replaces or deletes. Plain text. |
+| `by` | both, reply | The author, shown as written; a leading `@` is dropped. The avatar is the name's initial. |
+| `note` | both, reply | The card's text. Plain text. A suggestion with no note and no replies is only a redline, with no card. |
+| `mark` | suggestion | `track` (default): red strike, green insert. `pen`: a hand-drawn strike with the new words handwritten above. |
+| `#id` | both | The id a reply points at. Comments and suggestions share one id space. |
+| `reply` | reply | The `#id` of the thread it joins. |
+
+- A reply can sit anywhere in the document; it moves into its thread, and the paragraph it leaves empty is dropped. Put replies after the paragraph, or at the end.
+- Pen fits short changes only: both sides 24 characters or fewer, on one line, and plain text. Anything else draws as `track`, with no issue.
+- Write suggestions and comments in paragraphs and list items. In a heading or a table cell, and inside another one, they draw without a card, and the linter reports them.
+- On a page 50rem wide or more, each card sits in the right margin level with its line. On a narrow page the reader clicks a bubble to open its card under the line.
+- Don't overlap two anchors. Mark the words once, and reply to the thread.
+
+## Register
+
+- In `comark-ui`: on, as `comments`, in `comark-ui/html` only. `comments: { mark: "pen" }` draws every suggestion with the pen unless it sets its own `mark`.
+- Alone: `pnpm add comark @comark/html comark-comments`, then `createHtmlRenderer({ plugins: [comments()], components })` with `comments, { components }` from `comark-comments/html`. There are no Vue, React, or Svelte entries.

package/dist/skills/comark-ui/references/diagrams.md

@@ -21,10 +21,16 @@ queue -> map: pigeon pin
 | `goat` or `svgbob` | ASCII art, as lines and arrows |
 
 - The title in brackets after the language goes under the diagram and names it for screen readers. Give every diagram one.
-- Every other fence stays code, `mermaid` included, so draw flows in `d2` or `dot`.
+- Every other fence stays code, except `mermaid`, which comark-ui draws with comark-pele (see Mermaid below).
 - A diagram Kroki can't draw stays code, and `meta.issues` quotes the tool's error. So does one drawn while the server can't be reached; the next parse tries again.
 - The plugin drops anything that could run from the SVG: scripts, event handlers, embedded HTML, and animations. Write labels as plain text. A D2 Markdown label (`|md … |`) is embedded HTML, so it comes out empty, and nothing reports it.
 
+## Mermaid
+
+Through comark-ui, a ` ```mermaid ` fence is drawn as SVG by comark-pele while rendering, with no network, and themed with the other blocks. A diagram Pele can't draw shows its source, and nothing goes in `meta.issues`, so check it in a render.
+
+With `comark-ui/html`, a click, `Enter`, or `Space` zooms the diagram, and its buttons copy it as a PNG on the page's background or as its ` ```mermaid ` fence. The Vue, React, and Svelte entries draw the same buttons, and Pele zooms the diagram in place there. `zoom: false` in `comarkUi()` turns the zoom off; the buttons stay. A host with a strict Content Security Policy allows the buttons' script by the hash of `mermaidScript` from `comark-ui/html`, and Copy image needs `img-src data:`.
+
 ## Check each diagram
 
 Send an internal architecture or a schema with sensitive names only to the host's own Kroki server. With the default `server`, each diagram's source goes to `https://kroki.io`, a public service.