comark-ui 0.8.1 → 0.9.0

package/README.md

@@ -29,7 +29,9 @@ comarkUi({
 });
 ```
 
-`include` is off because it reads files from disk; turn it on to paste files into a document. `cast`, `table`, and `tests` are on but read no files until you pass `{ root }` or `{ read }`. When you parse in a browser, pass `chips: { download: false }`, since a browser may not download another site's images. comark-critic has no component for its styles, so put the exported `criticCss` in the page. The text around the blocks (headings, paragraphs, lists, tables, code, and quotes) is styled too, from shadcn/typeset on the same tokens and scoped to the document; pass `typeset: false` when your site already styles Markdown. See [Typeset](https://comark-ui.onmax.me/guide/typeset/).
+`include` is off because it reads files from disk; turn it on to paste files into a document. `cast`, `table`, and `tests` are on but read no files until you pass `{ root }` or `{ read }`. When you parse in a browser, pass `chips: { download: false }`, since a browser may not download another site's images. comark-critic has no component for its styles, so put the exported `criticCss` in the page. The text around the blocks (headings, paragraphs, lists, tables, code, and quotes) is styled too, from shadcn/typeset on the same tokens and scoped to the document; pass `typeset: false` when your site already styles Markdown. For content outside a document, such as an editor, import `comark-ui/typeset.css` and add the `comark-typeset` class. See [Typeset](https://comark-ui.onmax.me/guide/typeset/).
+
+It also returns `tags` and `blocks`. `tags` is every element a parsed document can hold besides the components; with the components' names, it's the allowlist for Comark's `security` plugin. `blocks` are the blocks the plugins replace while parsing, such as `::code-group`, which a linter needs beside the components' names.
 
 ## Renderers
 

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-import { t as typesetCss } from "./typeset-css-DdOGL7WF.mjs";
+import { n as typesetStylesheet, t as typesetCss } from "./typeset-css-DtOLAa1Z.mjs";
 //#region src/client.d.ts
 /**
  * comark-pele's diagrams on the shared `--comark-*` tokens, on a card like comark-diagrams'. Pele paints with its
@@ -19,4 +19,4 @@ export declare function mermaidBar(): string;
  */
 export declare function startMermaid(): () => void;
 //#endregion
-export { typesetCss };
+export { typesetCss, typesetStylesheet };

package/dist/client.mjs

@@ -1,3 +1,3 @@
-import { t as typesetCss } from "./typeset-css-blSNpFNK.mjs";
+import { n as typesetStylesheet, t as typesetCss } from "./typeset-css-BOtdXbMg.mjs";
 import { i as startMermaid, n as mermaidBar, r as mermaidCss, t as addMermaidStyles } from "./client-kUEiRbtp.mjs";
-export { addMermaidStyles, mermaidBar, mermaidCss, startMermaid, typesetCss };
+export { addMermaidStyles, mermaidBar, mermaidCss, startMermaid, typesetCss, typesetStylesheet };

package/dist/editor-vue.mjs

@@ -1,12 +1,9 @@
+import { n as isElement, t as childrenOf } from "./nodes-CwDBFXnO.mjs";
 import { c as fromMarkdown, l as toMarkdown, m as ComarkKit, s as checkMarkdown } from "./editor-9IcfELjG.mjs";
 import { Editor, EditorContent } from "@tiptap/vue-3";
 import { rowsOf } from "comark-properties";
 import { Properties } from "comark-properties/vue";
 import { defineComponent, h, onScopeDispose, ref, shallowRef, watch } from "vue";
-//#region ../../shared/nodes.ts
-const isElement = (node) => Array.isArray(node) && node[0] !== null;
-const childrenOf = ([, , ...rest]) => rest;
-//#endregion
 //#region src/editor-vue.ts
 /**
 * A Tiptap editor bound to a Markdown string: an edit writes the Markdown back, and a change from outside reloads the

package/dist/html.d.mts

@@ -1,4 +1,4 @@
-import { a as criticCss, n as Preset, r as PresetOptions } from "./index-DVGSDzBS.mjs";
+import { a as commentsCss, n as Preset, o as criticCss, r as PresetOptions } from "./index-Cq3zytGw.mjs";
 import { NodeHandler } from "comark";
 //#region src/html.d.ts
 /**
@@ -10,4 +10,4 @@ export declare const mermaidScript: string;
 /** Every plugin for `@comark/html`, with the `components` to render them. */
 declare const _default: (options?: PresetOptions) => Preset<NodeHandler>;
 //#endregion
-export { type PresetOptions, criticCss, _default as default };
+export { type PresetOptions, commentsCss, criticCss, _default as default };

package/dist/html.mjs

@@ -1,5 +1,5 @@
-import { t as typesetCss } from "./typeset-css-blSNpFNK.mjs";
-import { n as preset, t as criticCss } from "./src-PkmYCSNu.mjs";
+import { n as criticCss, r as preset, t as commentsCss } from "./src-MvpWiv9v.mjs";
+import { t as typesetCss } from "./typeset-css-BOtdXbMg.mjs";
 import { a as start, n as mermaidBar, r as mermaidCss } from "./client-kUEiRbtp.mjs";
 import { t as rawText } from "./text-D8j9clg3.mjs";
 import { escapeHtml } from "comark/utils";
@@ -111,4 +111,4 @@ var html_default = (options) => preset({
 	zoom
 }, options);
 //#endregion
-export { criticCss, html_default as default, mermaidScript };
+export { commentsCss, criticCss, html_default as default, mermaidScript };

package/dist/{index-DVGSDzBS.d.mts → index-Cq3zytGw.d.mts}

@@ -1,34 +1,78 @@
 import { CriticOptions, css as criticCss } from "comark-critic";
 import { FigureOptions } from "comark-figure";
 import { FootnotesOptions } from "comark-footnotes";
+import { CalloutsOptions, ReferencesOptions } from "comark-github";
 import { IconOptions, Icons } from "comark-icon";
 import { IncludeOptions } from "comark-include";
 import { KeysOptions } from "comark-keys";
 import { ReadingTimeOptions } from "comark-reading-time";
 import { XrefOptions } from "comark-xref";
 import { ComarkPlugin } from "comark";
+import { CommentsOptions, css as commentsCss } from "comark-comments";
 import { PropertiesOptions } from "comark-properties";
+import { PeleConfig } from "comark-pele";
 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";
-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 { QuizOptions } from "comark-quiz";
 import { TableOptions } from "comark-table";
 import { TabsOptions } from "comark-tabs";
 import { TestsOptions } from "comark-tests";
 import { ZoomOptions } from "comark-zoom";
+//#region src/mermaid-limits.d.ts
+type MermaidOptions = PeleConfig & {
+  /** How many diagrams a document draws. The ones after show their source as a code block. */
+  maxDiagrams?: number;
+  /** How many characters of Mermaid source a document draws, over all its diagrams. A diagram past it shows its source. */
+  maxSource?: number;
+};
+//#endregion
+//#region src/shiki.d.ts
+type Token = {
+  content: string;
+  color?: string;
+  htmlStyle?: Record<string, string>;
+};
+/** What the preset needs of a Shiki highlighter: a `HighlighterCore` from `shiki/core` fits it. */
+type ShikiHighlighter = {
+  codeToTokens(code: string, options: {
+    lang: string;
+    themes: {
+      light: string;
+      dark?: string;
+    };
+  }): {
+    tokens: Token[][];
+  };
+};
+type ShikiOptions = {
+  /**
+   * Your Shiki, with the fence's language loaded, or `undefined` to leave the block plain. It's called for each fenced
+   * block with a language that fits the remaining budget, so load each grammar once. Blocks past the limits skip it
+   * and report a limit issue without checking whether the language is supported.
+   */
+  highlighter: (language: string) => ShikiHighlighter | undefined | Promise<ShikiHighlighter | undefined>;
+  /** Theme names your highlighter has loaded. The dark one goes in `--shiki-dark`, which the typeset styles follow. */
+  themes: {
+    light: string;
+    dark?: string;
+  };
+  /** How many code blocks a document highlights. The ones after show without colors. */
+  maxBlocks?: number;
+  /** How many characters of code a document highlights, over all its blocks. A block past it shows without colors. */
+  maxSource?: number;
+};
+//#endregion
 //#region src/typeset.d.ts
 /** The node that adds the styles. The plugin adds one at the end of every document. */
 declare const TYPESET_TAG = "typeset-styles";
@@ -63,8 +107,11 @@ type PresetOptions = {
   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. */
-  mermaid?: PeleConfig | boolean;
+  /**
+   * Draws `mermaid` fences with comark-pele, on the server and offline. A host that renders documents it didn't write
+   * can pass `{ maxDiagrams, maxSource }`: the diagrams past either limit show their source as code, each with an issue.
+   */
+  mermaid?: MermaidOptions | boolean;
   /** HTML only: Vue, React, and Svelte have no diff components. */
   diff?: boolean;
   embed?: boolean;
@@ -108,6 +155,12 @@ type PresetOptions = {
   /** Reads no JUnit reports unless you pass `{ root }` or `{ read }`; inline reports render either way. */
   tests?: TestsOptions | boolean;
   zoom?: ZoomOptions | boolean;
+  /**
+   * Highlights fenced code with your own Shiki, before comark-code. Off unless you pass one, so the preset bundles no
+   * grammars. A host that renders documents it didn't write can pass `{ maxBlocks, maxSource }`: the blocks past either
+   * limit show without colors, each with an issue.
+   */
+  shiki?: ShikiOptions | false;
   code?: CodeOptions | boolean;
   codeNotes?: boolean;
   /**
@@ -176,8 +229,19 @@ type Renderer<C> = {
 type Preset<C> = {
   plugins: AnyPlugin[];
   components: Record<string, C>;
+  /**
+   * Every tag but `components`' that a document parsed with `plugins` can hold: Markdown's own, the raw HTML that
+   * GitHub's `html` plugin keeps, and the plain elements the plugins draw with. With `components`' names, it's the
+   * allowlist a host that sanitizes the tree needs. With GitHub's `html` off, raw HTML is left to the host.
+   */
+  tags: string[];
+  /**
+   * The blocks a document may write that the plugins turn into other nodes while parsing, such as `::code-group`. A
+   * linter that reports unknown components needs them beside `components`' names.
+   */
+  blocks: string[];
 };
 /** Builds a renderer's preset. Use the one from `comark-ui/html`, `/vue`, `/react`, or `/svelte`. */
 declare function preset<C>(renderer: Renderer<C>, options?: PresetOptions): Preset<C>;
 //#endregion
-export { criticCss as a, typeset as c, Renderer as i, Preset as n, preset as o, PresetOptions as r, TYPESET_TAG as s, AnyPlugin as t };
+export { commentsCss as a, TYPESET_TAG as c, ShikiOptions as d, MermaidOptions as f, Renderer as i, typeset as l, Preset as n, criticCss as o, PresetOptions as r, preset as s, AnyPlugin as t, ShikiHighlighter as u };

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-DVGSDzBS.mjs";
-export { AnyPlugin, Preset, PresetOptions, Renderer, TYPESET_TAG, criticCss, preset, typeset, typesetCss };
+import { n as typesetStylesheet, t as typesetCss } from "./typeset-css-DtOLAa1Z.mjs";
+import { a as commentsCss, c as TYPESET_TAG, d as ShikiOptions, f as MermaidOptions, i as Renderer, l as typeset, n as Preset, o as criticCss, r as PresetOptions, s as preset, t as AnyPlugin, u as ShikiHighlighter } from "./index-Cq3zytGw.mjs";
+export { AnyPlugin, type MermaidOptions, Preset, PresetOptions, Renderer, type ShikiHighlighter, type ShikiOptions, TYPESET_TAG, commentsCss, criticCss, preset, typeset, typesetCss, typesetStylesheet };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { t as typesetCss } from "./typeset-css-blSNpFNK.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 };
+import { a as typeset, i as TYPESET_TAG, n as criticCss, r as preset, t as commentsCss } from "./src-MvpWiv9v.mjs";
+import { n as typesetStylesheet, t as typesetCss } from "./typeset-css-BOtdXbMg.mjs";
+export { TYPESET_TAG, commentsCss, criticCss, preset, typeset, typesetCss, typesetStylesheet };

package/dist/nodes-CwDBFXnO.mjs

@@ -0,0 +1,5 @@
+//#region ../../shared/nodes.ts
+const isElement = (node) => Array.isArray(node) && node[0] !== null;
+const childrenOf = ([, , ...rest]) => rest;
+//#endregion
+export { isElement as n, childrenOf as t };

package/dist/react.d.mts

@@ -1,8 +1,8 @@
-import { a as criticCss, n as Preset, r as PresetOptions } from "./index-DVGSDzBS.mjs";
+import { a as commentsCss, n as Preset, o as criticCss, r as PresetOptions } from "./index-Cq3zytGw.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, comments, diff, and quiz. */
 declare const _default: (options?: PresetOptions) => Preset<AnyComponent>;
 //#endregion
-export { type PresetOptions, criticCss, _default as default };
+export { type PresetOptions, commentsCss, criticCss, _default as default };

package/dist/react.mjs

@@ -1,5 +1,5 @@
-import { t as typesetCss } from "./typeset-css-blSNpFNK.mjs";
-import { n as preset, t as criticCss } from "./src-PkmYCSNu.mjs";
+import { n as criticCss, r as preset, t as commentsCss } from "./src-MvpWiv9v.mjs";
+import { t as typesetCss } from "./typeset-css-BOtdXbMg.mjs";
 import { i as startMermaid, n as mermaidBar, t as addMermaidStyles } from "./client-kUEiRbtp.mjs";
 import { createElement, useEffect } from "react";
 import * as badge from "comark-badge/react";
@@ -94,4 +94,4 @@ var react_default = (options) => preset({
 	zoom
 }, options);
 //#endregion
-export { criticCss, react_default as default };
+export { commentsCss, criticCss, react_default as default };

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

@@ -45,7 +45,7 @@ Either way, the HTML renderer inlines the styles once per document, and the Vue,
 
 The `--comark-*` tokens theme every plugin at once; https://comark-ui.onmax.me/guide/theming/ lists them. In a Nuxt UI app the plugins follow its `--ui-*` variables with no setup. For a page rendered outside the app, such as review evidence, put the CSS from `nuxtUiTheme({ colors: appConfig.ui?.colors, css: mainCss })` (from `comark-ui/nuxt-ui`) in a `<style>`, so the page matches the app.
 
-A project that renders Markdown with remark moves to Comark with `remark-to-comark`; the [remark-to-comark reference](references/remark-to-comark.md) walks through it.
+To move a project to Comark, start with `migrate-to-comark`, which finds its Markdown libraries and runs the migrator for each; see the [migrate-to-comark reference](references/migrate-to-comark.md). A project that renders Markdown with remark moves to Comark with `remark-to-comark`; the [remark-to-comark reference](references/remark-to-comark.md) walks through it. One that renders with markdown-it moves with `markdown-it-to-comark`; see the [markdown-it-to-comark reference](references/markdown-it-to-comark.md). A project on marked moves with `marked-to-comark`; see the [marked-to-comark reference](references/marked-to-comark.md).
 
 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.
 

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

@@ -23,12 +23,12 @@ function close() {
 | `showLineNumbers` | Numbers the lines. |
 | `startLineNumber=120` | Numbers the lines from 120, and turns numbers on. |
 | `title="src/zoom.ts"` | Titles the block, like Comark's `[src/zoom.ts]`. A block without one shows its language. |
-| `frame="terminal"` | Draws a terminal window. `frame="code"` or `frame="none"` draws a plain block. |
+| `frame="terminal"` | Draws a terminal, with a line under its header. `frame="code"` or `frame="none"` draws a plain block. |
 | `wrap` | Starts the block with Wrap on. |
 
 A range is one line, `{7}`, a run, `{3-4}`, or a list of both, `{1, 3-4}`, always in braces. Ranges count the block's own lines from 1, folded lines included, whatever `startLineNumber` says: `startLineNumber=120 ins={3}` marks the line numbered 122.
 
-`sh`, `bash`, `zsh`, `shell`, `shellscript`, `shellsession`, `console`, and `ansi` blocks draw as terminals unless their title is a file name, such as `install.sh`. A terminal's header shows its title but not its language. In a code group the tab names the block, so a terminal there draws no window.
+`sh`, `bash`, `zsh`, `shell`, `shellscript`, `shellsession`, `console`, and `ansi` blocks draw as terminals unless their title is a file name, such as `install.sh`. A terminal's header shows its title but not its language. In a code group the tab names the block, so a terminal there draws no line under its header.
 
 When the host runs Shiki's notation transformers, comments such as `// [!code ++]`, `// [!code --]`, `// [!code highlight]`, `// [!code focus]`, `// [!code error]`, and `// [!code warning]` mark lines too, and comark-code styles them.
 

package/dist/skills/comark-ui/references/markdown-it-to-comark.md

@@ -0,0 +1,28 @@
+# Moving a project from markdown-it
+
+markdown-it-to-comark moves a project that renders Markdown with markdown-it to Comark. It reports what it finds as diagnostics, `MIC0101` to `MIC0303`, each with a fix and a link to https://comark-ui.onmax.me/markdown-it-to-comark/diagnostics/.
+
+## Run it
+
+```sh
+vp exec markdown-it-to-comark check . --json
+vp exec markdown-it-to-comark content "**/*.md" --write
+vp exec markdown-it-to-comark rewrite . --write
+vp exec markdown-it-to-comark check . --json
+```
+
+- `check` lists the markdown-it instances and framework hooks it finds, what each option and plugin becomes, the instances `rewrite` can replace and why the others stay, and the Markdown files `content` would change.
+- `rewrite` replaces `const md = new MarkdownIt(options).use(plugin)` with `const md = comarkOptions({ ...options, plugins: [markdownItPlugin(plugin)] })` and each `md.render(src)` with `(await renderHtml(src, md))`. It only does so when every `render` call is in an async function, since Comark renders asynchronously. Install `comark`, `@comark/html`, and `markdown-it-to-comark`.
+- `content` escapes `{`, `[`, and `:name` that Comark would read as attributes, spans, or components, and keeps an edit only if markdown-it renders the file byte for byte as before. It reads with the project's preset, options, and plugins, so `::: tip` containers and `[^1]` footnotes stay as written.
+- Run `check` again at the end. What's left is work for you: framework setups (MIC0101), plugins and hand-made changes nobody compared (MIC0105), setups it couldn't rewrite (MIC0201), and blocks left as written (MIC0303).
+
+## What it leaves to you
+
+- A framework's instance, such as VitePress' `markdown.config(md)` or Eleventy's `setLibrary("md", …)`, stays as it is: the framework renders. Render with `renderHtml(markdown, comarkOptions())` where the framework lets you.
+- A markdown-it plugin keeps its output on Comark through `markdownItPlugin(plugin, ...options)` from `markdown-it-to-comark/plugins`, renderer rules included. A comark-ui package that does the same job is reported with it (MIC0102); its markup differs.
+- A renderer rule set by hand (`md.renderer.rules.fence = …`) moves into a plugin function registered with `markdownItPlugin()`.
+
+## Register
+
+- In `comark-ui`: not included. Install it beside the preset for the migration.
+- Alone: `pnpm add -D markdown-it-to-comark`. It installs the command `markdown-it-to-comark`, the library, the Comark setup `markdown-it-to-comark/setup` and the bridge `markdown-it-to-comark/plugins` (add the package to your runtime dependencies when rewritten code imports them), and the Vite Doctor extension `markdown-it-to-comark/doctor`.

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

@@ -0,0 +1,28 @@
+# Moving a project from marked
+
+marked-to-comark moves a project that renders Markdown with marked to Comark. It reports what it finds as diagnostics, `MKC0101` to `MKC0304`, each with a fix and a link to https://comark-ui.onmax.me/marked-to-comark/diagnostics/.
+
+## Run it
+
+```sh
+vp exec marked-to-comark check . --json
+vp exec marked-to-comark content "posts/**/*.md" --write
+vp exec marked-to-comark rewrite . --write
+vp exec marked-to-comark check . --json
+```
+
+- `check` lists the marked setups it finds (the shared `marked`, `new Marked()` instances) and what each option and extension becomes, the calls `rewrite` can replace and why the others stay, and the Markdown files `content` would change. `--json` prints each finding with its code, file, line, fix, and docs link.
+- `rewrite` replaces `marked.parse(markdown)` inside an async function with `await renderHtml(markdown, comarkOptions({ … }))`, importing `comarkOptions` from `marked-to-comark/setup`. Install what the new code imports: `comark`, `@comark/html`, and `marked-to-comark`.
+- `content` escapes `{`, `[`, and `:name` that Comark would read as attributes, spans, or components, so marked still renders every file byte for byte as before. It checks each edit with the project's own marked. Run it before `rewrite`, which removes the marked setup it reads options from.
+- Run `check` again at the end. What's left is work for you: custom renderers and extensions (MKC0105), options with no counterpart (MKC0106), calls it couldn't rewrite (MKC0201), and blocks left as written (MKC0303).
+
+## What it leaves to you
+
+- A call in a function that isn't async stays: `renderHtml` returns a promise. Make the function async, update its callers, and run `rewrite` again.
+- A custom `renderer` method becomes a component for the element it draws (`components: { a }` in @comark/html, or your framework's renderer); a tokenizer or extension becomes a Comark plugin.
+- Strings marked renders at runtime, such as chat replies, need no content changes. For a reply that streams in, render with `{ ...comarkOptions(), autoClose: true }` so unfinished Markdown looks finished at every step.
+
+## Register
+
+- In `comark-ui`: not included. Install it beside the preset for the migration.
+- Alone: `pnpm add -D marked-to-comark`. It installs the command `marked-to-comark`, the library `marked-to-comark`, the Comark setup `marked-to-comark/setup` (add it to your runtime dependencies when rewritten code imports it), and the Vite Doctor extension `marked-to-comark/doctor`.

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

@@ -0,0 +1,33 @@
+# Moving a project to Comark
+
+migrate-to-comark finds the Markdown libraries a project uses and moves it with each library's migrator: remark-to-comark, markdown-it-to-comark, and marked-to-comark. Start here when you don't know which library the project uses, or it uses more than one.
+
+## Run it
+
+```sh
+npx migrate-to-comark --json             # what it found and would change; writes nothing
+npx migrate-to-comark --yes              # write every change
+npx migrate-to-comark --yes --only marked   # one library at a time
+```
+
+- It reads every package.json for remark, markdown-it, and marked, and the frameworks built on them: Astro, Docusaurus, and react-markdown for remark; VitePress, VuePress, and Eleventy for markdown-it; svelte-markdown and ngx-markdown for marked.
+- It writes only what each migrator's `rewrite --write` and `content --write` would. A file two migrators want goes to the library its nearest package.json declares. When that doesn't settle it, `conflicts` in the JSON names the file and both migrators, and the file stays as it is.
+- Code that renders Markdown switches last. While a Markdown file its migrator handles needs a hand fix or is in `conflicts`, `held` in the JSON names the code file and the Markdown files it waits on. Fix those, then run it again.
+- In an agent's shell it can't ask, so without `--yes` it reports and writes nothing.
+
+## What it leaves to you
+
+Everything each migrator reports. Run each one's check at the end, and follow its reference for the fixes:
+
+```sh
+npx remark-to-comark check . --json
+npx markdown-it-to-comark check . --json
+npx marked-to-comark check . --json
+```
+
+See the [remark-to-comark](remark-to-comark.md), [markdown-it-to-comark](markdown-it-to-comark.md), and [marked-to-comark](marked-to-comark.md) references.
+
+## Register
+
+- In `comark-ui`: not included. Run it with `npx`, or install it beside the preset for the migration.
+- Alone: `pnpm add -D migrate-to-comark`. It installs the command `migrate-to-comark`, the library `migrate-to-comark` (`detect`, `plan`, `apply`), and the three migrators.

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

@@ -49,7 +49,7 @@ Promise callbacks are microtasks, and a timer's callback is a task.
 - Options are shuffled the same way for every reader, so do not write options that point at others by place, such as "All of the above" or "Both A and B". Keep the options about as long as each other, since a right option much longer than the rest is reported.
 - Keep a block to six options or fewer. Mark at least one right option in a question, or ask it as a poll. Put no block inside another block's prompt, option, or slot.
 
-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.
+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` (or `window.__comarkQuizState` set before the script runs). In an iframe, `data-quiz-relay` on the lesson's `<html>` relays all three over postMessage to the parent; 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/remark-to-comark.md

@@ -5,10 +5,16 @@ remark-to-comark moves a project that renders Markdown with remark, rehype, unif
 ## Run it
 
 ```sh
-vp exec remark-to-comark check . --json
+vp exec remark-to-comark migrate
+```
+
+`migrate` runs `content --write`, then `rewrite --write`, then `check`, on a clean git tree (`--force` skips that check). To review each step first, run them yourself:
+
+```sh
+vp exec remark-to-comark check --json
 vp exec remark-to-comark content "**/*.{md,mdx}" --write
-vp exec remark-to-comark rewrite . --write
-vp exec remark-to-comark check . --json
+vp exec remark-to-comark rewrite --write
+vp exec remark-to-comark check --json
 ```
 
 - `check` lists the remark setups it finds and what each plugin becomes, the unified chains `rewrite` can replace and why the others stay, the Markdown files `content` would change, and the MDX it leaves alone. `--json` prints each finding with its code, file, line, fix, and docs link.

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

@@ -4,7 +4,7 @@ comark-ui registers every comark-ui package for one renderer, in the order they
 
 ## Options
 
-`comarkUi(options)` returns `{ plugins, components }`. Each key is a package's name without `comark-`, in camelCase, such as `fileTree`, `codeNotes`, or `readingTime`. The exceptions are `math` for comark-mathml, `outline` for comark-outline, and `mermaid` and `typeset`, which are not packages. `false` turns a plugin off along with its components, and an object turns it on with those options. `true` turns on `include` and leaves the others as they are:
+`comarkUi(options)` returns `{ plugins, components }`. Each key is a package's name without `comark-`, in camelCase, such as `fileTree`, `codeNotes`, or `readingTime`. The exceptions are `math` for comark-mathml, `outline` for comark-outline, and `mermaid`, `shiki`, and `typeset`, which are not packages. `false` turns a plugin off along with its components, and an object turns it on with those options. `true` turns on `include` and leaves the others as they are:
 
 ```ts
 comarkUi({
@@ -26,6 +26,7 @@ comarkUi({
 - Media sizing reads only data URIs by default. `zoom: { size: true }` and `media: { size: true }` also fetch remote files while parsing, and `annotate: { size: true }` does so at HTML render time. Enable these only for trusted documents, because the requests follow redirects and can reach private networks. `{ size: false }` turns measurement off for that 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.
 - `mermaid` draws `mermaid` fences with comark-pele, on the server and offline. In the HTML entry the diagram zooms with comark-zoom unless `zoom` is `false`. `mermaid: false` turns it off.
+- `shiki` highlights fenced code with your own Shiki, before comark-code: `{ highlighter: (language) => shiki | undefined, themes: { light, dark } }`. It is off until you pass it, so the preset bundles no grammars. `maxBlocks` and `maxSource` cap how many blocks, and how many characters of code, a document highlights; the blocks past them show plain, each with an issue.
 - comark-critic has no component to add its styles, so put `criticCss`, which every entry exports, in the page.
 - The preset styles the text around the blocks, 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`.