comark-ui 0.7.2 → 0.7.5

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-Dbqxt4Qg.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-Dbqxt4Qg.d.mts}

@@ -8,10 +8,12 @@ import { ReadingTimeOptions } from "comark-reading-time";
 import { XrefOptions } from "comark-xref";
 import { ComarkPlugin } from "comark";
 import { BadgeOptions } from "comark-badge";
+import { AnnotateOptions } from "comark-annotate";
 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";
@@ -42,7 +44,7 @@ type PresetOptions = {
   /** Pastes files into the Markdown before the other plugins read it. Off, since it reads from disk by default. */
   include?: IncludeOptions | boolean;
   /** HTML only: Vue, React, and Svelte have no annotate components. */
-  annotate?: boolean;
+  annotate?: AnnotateOptions | boolean;
   carousel?: boolean;
   /** Reads no cast files unless you pass `{ root }` or `{ read }`; inline casts render either way. */
   cast?: CastOptions | boolean;
@@ -54,6 +56,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. */
@@ -116,12 +123,13 @@ type Part<C, O = void> = {
 };
 /** One renderer's entry of each package with components, by the option that turns it on. */
 type Renderer<C> = {
-  annotate?: Part<C>;
+  annotate?: Part<C, AnnotateOptions>;
   carousel: Part<C>;
   cast: Part<C, CastOptions>;
   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-Dbqxt4Qg.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-Dbqxt4Qg.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,13 +53,15 @@ 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
 
 - In `comark-ui`: on, in `comark-ui/html` only.
-- Alone: `pnpm add comark @comark/html comark-annotate`, then `createHtmlRenderer({ plugins: [annotate()], components })` with both from `comark-annotate/html`. It renders only to HTML and takes no options. Each document inlines the styles once, with style attributes for positions, so a strict Content Security Policy needs `style-src 'unsafe-inline'`.
+- Alone: `pnpm add comark @comark/html comark-annotate`, then `createHtmlRenderer({ plugins: [annotate()], components })` with both from `comark-annotate/html`. It renders only to HTML. Screenshots reserve their `viewport`, or dimensions from a data URI. `annotate({ size: true })` also fetches remote screenshots at render time; enable it only for trusted documents, since requests follow redirects and can reach private networks. `annotate({ size: false })` disables measurement while retaining authored viewports. In `comark-ui`, put these options under `annotate`. Each document inlines the styles once, with style attributes for positions, so a strict Content Security Policy needs `style-src 'unsafe-inline'`.

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/media.md

@@ -12,7 +12,7 @@ The spinner now stops once the build finishes:
 
 - A `src` that ends in `.mp4`, `.webm`, `.mov`, or `.m4v`, before any `?` or `#`, plays as a video, and one in `.mp3`, `.wav`, `.ogg`, or `.m4a` as audio. Every other image stays an image.
 - The alt text is required. It names the player for screen readers, and it's the text of a link to the file where the browser can't play it.
-- `autoplay`, `loop`, and `muted` are off by default. Browsers start a file by itself only when it's muted, so `autoplay` needs `muted`. `poster="frame.png"` shows an image before a video plays; audio takes none. `{loop=false}` turns a prop off. Other props, such as `width` or a class, are dropped and reported.
+- `autoplay`, `loop`, and `muted` are off by default. Browsers start a file by itself only when it's muted, so `autoplay` needs `muted`. `poster="frame.png"` shows an image before a video plays; audio takes none. `{loop=false}` turns a prop off. A video's `width` and `height` must be paired whole pixel dimensions, like `{width=1280 height=720}`, to reserve its room before loading. Audio takes neither. Other props, such as a class, are dropped and reported.
 - A GitHub attachment link, `https://github.com/user-attachments/assets/<id>`, plays as a video when the bare URL sits alone in its paragraph, as on GitHub. With text of its own, or inside a sentence, it stays a link.
 
 ## Record the evidence
@@ -25,5 +25,5 @@ The spinner now stops once the build finishes:
 
 ## Register
 
-- In `comark-ui`: on. `media: { controls: "native" }` keeps the browser's own controls and leaves the script out.
+- In `comark-ui`: on. `media: { controls: "native" }` keeps the browser's own controls and leaves the script out. Measurement reads only data URIs by default. `media: { size: true }` also measures remote videos while parsing; use it only for trusted documents, since requests follow redirects and can reach private networks. `media: { size: false }` disables measurement. Authored dimensions work with any setting. Alone, pass the same options to `media()`.
 - Alone: `pnpm add comark @comark/html comark-media`, then `createHtmlRenderer({ plugins: [media()], components })` with both from `comark-media/html`. `comark-media/vue`, `/react`, and `/svelte` render it too. Its place in `plugins` doesn't matter. It reads the tokens before any plugin sees the tree, so comark-zoom never zooms a video and comark-chips never turns an attachment link into a chip. The HTML renderer inlines the players' script once per document, and the browser's own controls show until it runs and whenever a file can't play.

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

@@ -22,7 +22,8 @@ comarkUi({
 
 - Every plugin except `include`, which reads files from disk. `include: { root, base }` turns it on, or `{ read }` in a browser or an edge runtime. `include: true` reads under the working directory.
 - `cast`, `table`, and `tests` get a reader that finds no file. Inline casts, CSV fences, and pasted JUnit reports render, and a `src` file doesn't load until you pass `{ root }` or `{ read }`. Any other options object replaces that reader too, so the plugin reads under the working directory.
-- Three plugins use the network while parsing: `chips` downloads favicons and avatars, `icon` fetches icon sets from the Iconify API, and `diagrams` sends each diagram's source to `https://kroki.io`. In a browser, pass `chips: { download: false }`, since a browser may not download another site's images. To parse offline, also pass `icon: { fetch: false }` with your icon sets in `collections`, and `diagrams: { draw: false }`. To keep diagram sources private, pass your own Kroki `server`.
+- By default, three plugins use the network while parsing: `chips` downloads favicons and avatars, `icon` fetches icon sets from the Iconify API, and `diagrams` sends each diagram's source to `https://kroki.io`. In a browser, pass `chips: { download: false }`, since a browser may not download another site's images. To parse offline, also pass `icon: { fetch: false }` with your icon sets in `collections`, and `diagrams: { draw: false }`. To keep diagram sources private, pass your own Kroki `server`.
+- Media sizing reads only data URIs by default. `zoom: { size: true }` and `media: { size: true }` also fetch remote files while parsing; `annotate: { size: true }` does so at HTML render time. Enable these only for trusted documents, since requests follow redirects and can reach private networks. `{ size: false }` disables measurement for each plugin; authored dimensions and screenshot viewports still work.
 - `icon`'s options apply to every icon the preset draws, in cards, details, file trees, tabs, and code actions too.
 - comark-critic has no component to add its styles, so put `criticCss`, which every entry exports, in the page.
 - The text around the blocks is styled by default, scoped to the element the document renders into, on the same `--comark-*` tokens. Pass `typeset: false` when the site already styles Markdown, such as with Tailwind Typography's `prose`.
@@ -36,7 +37,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/comark-ui/references/zoom.md

@@ -31,5 +31,5 @@ The zoomed view fires `comark-zoom:open`, `comark-zoom:change`, and `comark-zoom
 
 ## Register
 
-- In `comark-ui`: on, as `zoom`. `zoom: { images: false }` leaves images alone, so only `::zoom` blocks and elements marked `{data-zoom}` zoom.
+- In `comark-ui`: on, as `zoom`. `zoom: { images: false }` leaves images alone, so only `::zoom` blocks and elements marked `{data-zoom}` zoom. Data URI images get dimensions by default; one authored pixel side gets the other at the file's ratio. Images with both sides or a side such as `50%` keep them. `zoom: { size: true }` also measures remote images while parsing; use it only for trusted documents, since requests follow redirects and can reach private networks. `zoom: { size: false }` disables measurement. Alone, pass the same options to `zoom()`.
 - Alone: `pnpm add comark @comark/html comark-zoom`, then `createHtmlRenderer({ plugins: [zoom()], components })` with both from `comark-zoom/html`. `comark-zoom/vue`, `/react`, and `/svelte` export the same pair for those renderers. The plugin adds a node that starts the script, so pass the components even when only images zoom. A page with no renderer calls `start()` from `comark-zoom/client` once. comark-annotate and comark-carousel zoom their own blocks without it, so register `zoom()` for images and `::zoom`.