comark-ui 0.7.2 → 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,4 +1,4 @@
-import { a as criticCss, n as Preset, r as PresetOptions } from "./index-jkwx6SyG.mjs";
+import { a as criticCss, n as Preset, r as PresetOptions } from "./index-BUDHsvnm.mjs";
 import { NodeHandler } from "comark";
 //#region src/html.d.ts
 /**

package/dist/html.mjs

@@ -1,5 +1,5 @@
 import { t as typesetCss } from "./typeset-css-5aJ7cSmh.mjs";
-import { n as preset, t as criticCss } from "./src-DROB05U6.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";
@@ -12,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";
@@ -77,6 +78,7 @@ var html_default = (options) => preset({
 	code,
 	codeNotes,
 	colors,
+	comments,
 	details,
 	diagrams,
 	diff,

package/dist/{index-jkwx6SyG.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";
@@ -54,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. */
@@ -122,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>;

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-jkwx6SyG.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-5aJ7cSmh.mjs";
-import { i as typeset, n as preset, r as TYPESET_TAG, t as criticCss } from "./src-DROB05U6.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-jkwx6SyG.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,5 +1,5 @@
 import { t as typesetCss } from "./typeset-css-5aJ7cSmh.mjs";
-import { n as preset, t as criticCss } from "./src-DROB05U6.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";
@@ -57,7 +57,7 @@ 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.
@@ -59,6 +65,7 @@ Read the reference for each block you use before you write it. Mix the blocks fr
 | 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/lint.md

@@ -5,7 +5,7 @@ comark-linter reports what Comark forgives, such as a `::` block never closed, a
 ## Run the command
 
 ```sh
-npx lint-comark "docs/**/*.md" --format json --check-urls
+vp exec lint-comark "docs/**/*.md" --format json --check-urls
 ```
 
 - Pass files or globs. Quote a glob so the shell passes it as written; lint-comark expands it and skips `node_modules` and `dist`.

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

@@ -37,7 +37,7 @@ Promise callbacks are microtasks, and a timer's callback is a task.
 
 A question uses radios when one option is marked `[x]`; `multiple` makes it a checkbox question. Options are shuffled deterministically unless `shuffle="false"`. Questions and recall cards share numbering, while polls are not numbered. A missing id is derived from the block content. Use `#hint` and `#explain` on questions, and `#answer` on recall cards. Polls accept `multiple` and a date in `closes`.
 
-The HTML renderer inlines the quiz script and styles. Hosts can listen for `comark-quiz:answer` and `comark-quiz:ready`, and restore answers or results with `comark-quiz:state`; see the package [getting started guide](../../packages/quiz/docs/getting-started.md) for the event shapes and storage behavior.
+The HTML renderer inlines the quiz script and styles. Hosts can listen for `comark-quiz:answer` and `comark-quiz:ready`, and restore answers or results with `comark-quiz:state`; see [Saving answers](https://comark-ui.onmax.me/quiz/#saving-answers) on its page for the event shapes and storage behavior.
 
 ## Register
 

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

@@ -36,7 +36,7 @@ comarkUi({
 | `@comark/react` | `comark-ui/react` |
 | `@comark/svelte` | `comark-ui/svelte` |
 
-The Vue, React, and Svelte entries leave out annotate and diff, which render only to HTML. Screenshots, compares, diffs, and the marks on charts need `comark-ui/html`.
+The Vue, React, and Svelte entries leave out annotate, comments, diff, and quiz, which render only to HTML. Screenshots, compares, diffs, suggestions and comments, and the marks on charts need `comark-ui/html`.
 
 To use another renderer, install it in place of `@comark/html`, such as `pnpm add comark @comark/vue comark-ui`, and pass it `plugins` and `components` as you would one package's. The preset needs Vue 3.5, React 18, or Svelte 5.20 or later. Every entry exports the `PresetOptions` type, and `comark-ui` itself exports `preset(renderer, options)`, which builds the same pair from renderer entries you pass.
 

package/dist/skills/review-document/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: review-document
+description: Turns a review's findings into one short Markdown document a reader can act on, with the verdict first and each finding ranked, located, backed by evidence, and paired with its fix. Use when writing up a code review, a design or QA review, an audit, or any report whose reader must decide what to do next.
+license: MIT
+---
+
+# Review document
+
+A review's reader has one question: what do I do now? Answer it in the first two lines, then give each finding just enough evidence that the reader trusts it without redoing your work. This skill organizes findings you already have; finding them is the review itself.
+
+Length is the usual failure. A reader who has to dig through praise, process, and restated findings misses the one that blocks the merge. Every line below the verdict either supports a finding or says what you didn't check.
+
+## 1. Decide the verdict
+
+Pick one: **approve**, **approve with changes**, **request changes**, or **blocked** on a named thing. Under it, write the reason in one sentence that names the finding behind it.
+
+Done when someone who reads only the verdict knows what to do.
+
+## 2. Keep the findings that change the decision
+
+- Keep a finding when fixing it, or not, changes what the reader should do.
+- Merge findings with one root cause into one, and list every place it appears.
+- Rank each one: **blocking** (wrong results, lost data, a security hole, broken for users), **should fix** (a real cost that can wait), or **nit**, only when the reader asked for them.
+
+Order them blocking first. Done when every finding has a rank and no two share a cause.
+
+## 3. Back each finding
+
+Each finding is four parts, in this order:
+
+1. **A title that states the consequence**, for whom: "Small avatars load the 512px image", not "Cache key issue".
+2. **Where**: the file and line, linked when there's a URL.
+3. **Evidence**, the strongest you have: a failing test or command you ran (`::tests`, a fenced block of output), a screenshot of the wrong state (measured as the before-after-evidence skill describes), the lines that cause it (a fence with the line highlighted), then reasoning. Say which it is: a finding you reproduced reads differently from one you read in the code.
+4. **The fix**: a `::diff` of the smallest change, or one sentence when the fix is a decision for the reader.
+
+Done when every blocking finding has evidence you ran or captured, or says plainly that it comes from reading the code.
+
+## 4. Say what you checked
+
+End with two short lists: what you checked and how, and what you didn't check. A review that implies more coverage than it had loses the reader's trust in the parts that were real.
+
+## 5. Write it
+
+Follow [references/example.md](references/example.md):
+
+- The verdict in a callout: `> [!CAUTION]` for request changes or blocked, `> [!WARNING]` for approve with changes, `> [!TIP]` for approve.
+- One `##` heading per finding, numbered, with its rank in the heading. About a dozen lines each, evidence included.
+- No summary that repeats the findings, no section for an empty rank, no list of what's good unless the reader asked.
+
+[references/blocks.md](references/blocks.md) has the syntax for the callout, `::tests`, `::diff`, and highlighted lines.
+
+## 6. Check the render
+
+1. Lint it, and fix until it reports no problems:
+
+   ```sh
+   vp dlx --package comark-linter --package comark-ui lint-comark review.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 rendered page where it will be read and read it top to bottom as the reader would. Each finding's evidence should be visible without expanding anything except a long log, and each `::diff` should start at the line its finding names.
+
+Done when the page renders without problems and you've read it once as the reader.

package/dist/skills/review-document/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Review document"
+  short_description: "Write findings as a verdict, evidence, and fixes"