comark-code-notes 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,69 @@
+MIT License
+
+Copyright (c) 2026 onmax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The icons are Lucide's (https://lucide.dev), under its license:
+
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# comark-code-notes
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://comark-ui.onmax.me/badge.svg?source=npm-version&package=comark-code-notes&icon=npm)](https://npmx.dev/package/comark-code-notes)
+[![npm downloads](https://comark-ui.onmax.me/badge.svg?source=npm-downloads&package=comark-code-notes&period=month&icon=npm)](https://npmx.dev/package/comark-code-notes)
+[![license](https://comark-ui.onmax.me/badge.svg?label=license&value=MIT)](https://npmx.dev/package/comark-code-notes)
+[![docs](https://comark-ui.onmax.me/badge.svg?label=docs&value=comark-ui.onmax.me)](https://comark-ui.onmax.me/code-notes/)
+
+Numbered notes on lines of code, as in Quarto and AsciiDoc: a `// <1>` comment at the end of a line becomes a marker, and the numbered list after the fence becomes its notes, each linked to its marker and back. A [Comark](https://comark.dev) plugin for HTML, Vue, React, and Svelte.
+
+```sh
+pnpm add comark comark-code-notes
+```
+
+```ts
+import { createHtmlRenderer } from "@comark/html";
+import shiki from "@comark/html/plugins/shiki";
+import codeNotes, { components } from "comark-code-notes/html";
+
+const render = createHtmlRenderer({ plugins: [shiki(), codeNotes()], components });
+```
+
+````md
+```ts
+const res = await fetch(url) // <1>
+if (!res.ok) return 0 // <2>
+```
+
+1. One request per plaza, so the counts load in parallel.
+2. A plaza with no census yet counts as empty.
+````
+
+Markers sit in a line-end comment: `// <1>`, `# <1>`, `-- <1>`, `; <1>`, `/* <1> */`, or `<!-- <1> -->`. They are taken out before Shiki highlights the code and drawn into its lines after, so put `codeNotes()` after `shiki()`. The marker's number is CSS, so copying the code, by hand or with comark-code's button, leaves it out. A fence with no numbered list after it, and any ` ```md ` fence, stays as written.
+
+The plugin adds every problem to `meta.issues`, so a host can reject a document before publishing it: markers with no list, a marker with no note, a note with no marker, and `shiki` after the plugin. Each issue names its fence and says how to fix it.
+
+## Renderers
+
+| Renderer | Import |
+| --- | --- |
+| `@comark/html` | `comark-code-notes/html`: the styles are inlined once per document |
+| `@comark/vue` | `comark-code-notes/vue` |
+| `@comark/react` | `comark-code-notes/react` |
+| `@comark/svelte` | `comark-code-notes/svelte` |
+
+Each entry exports the parse plugin as `default` and the renderer's `components`. The Vue, React, and Svelte components add the styles when they mount; import `comark-code-notes/style.css` with your styles so a server-rendered page doesn't shift. The styles read the shared `--comark-*` tokens and sit in a `comark` CSS layer, so any plain rule of your own wins.

package/dist/client.d.mts

@@ -0,0 +1,13 @@
+//#region src/styles.d.ts
+/**
+ * Round numbered markers at the ends of lines and before each note, as a soft tint of shadcn/ui's `--primary` when the
+ * page has it, or of the foreground otherwise, with the number in that color, on the shared `--comark-*` tokens.
+ * Override `--cn-marker` and `--cn-marker-text`. The number is drawn by CSS, so copying the code never takes it along.
+ * The rules sit in the `comark` layer, so any unlayered rule of the host's wins.
+ */
+export declare const css: string;
+//#endregion
+//#region src/client.d.ts
+/** Adds the code notes styles to the page once. The Vue, React, and Svelte components call it when they mount. */
+export declare function addStyles(): void;
+//#endregion

package/dist/client.mjs

@@ -0,0 +1,12 @@
+import { t as css } from "./styles-zxOi3Y7k.mjs";
+//#region src/client.ts
+/** Adds the code notes styles to the page once. The Vue, React, and Svelte components call it when they mount. */
+function addStyles() {
+	if (document.querySelector("style[data-comark-code-notes]")) return;
+	const style = document.createElement("style");
+	style.dataset.comarkCodeNotes = "";
+	style.textContent = css;
+	document.head.append(style);
+}
+//#endregion
+export { addStyles, css };

package/dist/html.d.mts

@@ -0,0 +1,7 @@
+import _default, { CodeNotesAttributes, CodeNotesMeta, NOTES_TAG } from "./index.mjs";
+import { NodeHandler } from "comark";
+//#region src/html.d.ts
+/** The HTML renderer for code notes. Pass it as `components`; it inlines the styles once per document. */
+export declare const components: Record<"code-notes", NodeHandler>;
+//#endregion
+export { type CodeNotesAttributes, type CodeNotesMeta, NOTES_TAG, _default as default };

package/dist/html.mjs

@@ -0,0 +1,18 @@
+import src_default, { NOTES_TAG } from "./index.mjs";
+import { t as css } from "./styles-zxOi3Y7k.mjs";
+//#region src/html.ts
+const styled = /* @__PURE__ */ new WeakSet();
+const notes = async ([, attrs, ...children], state) => {
+	const styles = styled.has(state.context) ? "" : `<style data-comark-code-notes>${css}</style>`;
+	styled.add(state.context);
+	const start = Number(attrs.start);
+	return `${styles}<ol class="cn-notes"${Number.isInteger(start) && start !== 1 ? ` start="${start}"` : ""}>${await state.flow([
+		"div",
+		{},
+		...children
+	], state)}</ol>`;
+};
+/** The HTML renderer for code notes. Pass it as `components`; it inlines the styles once per document. */
+const components = { "code-notes": notes };
+//#endregion
+export { NOTES_TAG, components, src_default as default };

package/dist/index.d.mts

@@ -0,0 +1,22 @@
+//#region src/index.d.ts
+export type CodeNotesMeta = {
+  /** One readable sentence per problem with a fence's markers or notes. Other plugins add theirs too. */
+  issues: string[];
+  /** The comark-linter rule of each issue, by its sentence, so the linter reports it under its own code. */
+  issueRules: Record<string, string>;
+};
+/** The node the numbered list after an annotated fence becomes. Each item starts with its marker, linking back. */
+export declare const NOTES_TAG = "code-notes";
+/** What a `code-notes` node carries besides its items: the number of its first note. */
+export type CodeNotesAttributes = {
+  start?: number;
+};
+/**
+ * Turns `// <1>` at the end of a line in a fence, in the language's comment, into a numbered marker, and the numbered
+ * list right after the fence into its notes, each linked to its marker and back. Markers are stripped before Shiki
+ * highlights the code and drawn into its lines after, so put this plugin after Comark's `shiki` in `plugins`.
+ * Problems are added to `meta.issues`.
+ */
+declare const _default: import("comark").ComarkPluginFactory<void, CodeNotesMeta, {}>;
+//#endregion
+export { _default as default };

package/dist/index.mjs

@@ -0,0 +1,213 @@
+import { defineComarkPlugin } from "comark";
+//#region src/index.ts
+/** The node the numbered list after an annotated fence becomes. Each item starts with its marker, linking back. */
+const NOTES_TAG = "code-notes";
+const MARKERS = String.raw`<\d+>(?:\s*<\d+>)*`;
+const ALONE = new RegExp(String.raw`\s*(?:(?://|#|--|;|%)\s*(${MARKERS})|(?:/\*|<!--)\s*(${MARKERS})\s*(?:\*/|-->))\s*$`);
+const AFTER_WORDS = new RegExp(String.raw`((?://|#|--|;|%).*?\S)\s+(${MARKERS})\s*$`);
+const BLOCK_WORDS = new RegExp(String.raw`^(.*?)(/\*|<!--)(.*?)\s+(${MARKERS})\s*(\*/|-->)\s*$`);
+const MARKDOWN = /* @__PURE__ */ new Set([
+	"md",
+	"mdc",
+	"markdown",
+	"comark"
+]);
+const isElement = (node) => Array.isArray(node) && node[0] !== null;
+const childrenOf = ([, , ...rest]) => rest;
+const textOf = (node) => !Array.isArray(node) ? node : isElement(node) ? childrenOf(node).map(textOf).join("") : "";
+const numbers = (markers) => [...markers.matchAll(/\d+/g)].map(([digits]) => Number(digits));
+function hash(text) {
+	let value = 2166136261;
+	for (let at = 0; at < text.length; at++) value = Math.imul(value ^ text.charCodeAt(at), 16777619);
+	return (value >>> 0).toString(36);
+}
+/** Strips the markers off each line, and says where they were. */
+function strip(content) {
+	const markers = /* @__PURE__ */ new Map();
+	return {
+		code: content.split("\n").map((line, index) => {
+			const alone = ALONE.exec(line);
+			if (alone) {
+				markers.set(index, numbers(alone[1] ?? alone[2] ?? ""));
+				return line.slice(0, alone.index);
+			}
+			const block = BLOCK_WORDS.exec(line);
+			if (block) {
+				markers.set(index, numbers(block[4] ?? ""));
+				return `${block[1] ?? ""}${block[2] ?? ""}${(block[3] ?? "").trimEnd()} ${block[5] ?? ""}`;
+			}
+			const words = AFTER_WORDS.exec(line);
+			if (!words) return line;
+			markers.set(index, numbers(words[2] ?? ""));
+			return line.slice(0, words.index) + (words[1] ?? "");
+		}).join("\n"),
+		markers
+	};
+}
+/**
+* Takes the markers out of every fence a numbered list follows, before any plugin's `post`, so Shiki highlights the
+* code without them in any plugin order.
+*/
+function read(tokens) {
+	const fences = [];
+	let count = 0;
+	for (const [index, token] of tokens.entries()) {
+		if (token.type !== "fence") continue;
+		count++;
+		const language = token.info.trim().split(/[\s[{]/, 1)[0] ?? "";
+		if (MARKDOWN.has(language.toLowerCase())) continue;
+		const { code, markers } = strip(token.content);
+		if (!markers.size) continue;
+		const name = `The \`\`\`${language} fence ${count}`;
+		const notes = tokens[index + 1]?.type === "ordered_list_open";
+		if (notes) token.content = code;
+		fences.push({
+			name,
+			code: (notes ? code : token.content).replace(/\n+$/, ""),
+			markers,
+			notes,
+			order: count
+		});
+	}
+	return fences;
+}
+const link = (note, uid, first) => ["a", {
+	class: "cn-marker",
+	href: `#${uid}-${note}`,
+	...first && { id: `${uid}-${note}-ref` },
+	"data-note": String(note),
+	"aria-label": `Note ${note}`
+}];
+const marker = (note, uid, first, known) => known.has(note) ? link(note, uid, first) : ["span", {
+	class: "cn-marker",
+	"data-note": String(note)
+}];
+/** Adds each line's markers to its end, in Shiki's line spans or in the plain code. */
+function draw(code, fence, uid, known) {
+	const seen = /* @__PURE__ */ new Set();
+	const markersOf = (line) => (fence.markers.get(line) ?? []).map((note) => {
+		const first = !seen.has(note);
+		seen.add(note);
+		return marker(note, uid, first, known);
+	});
+	const lines = childrenOf(code).filter((child) => isElement(child) && child[0] === "span");
+	if (lines.length) {
+		for (const [index, line] of lines.entries()) line.push(...markersOf(index));
+		return;
+	}
+	const drawn = textOf(code).split("\n").flatMap((line, index) => [...index ? ["\n"] : [], [
+		"span",
+		{ class: "line" },
+		line,
+		...markersOf(index)
+	]]);
+	code.splice(2, code.length - 2, ...drawn);
+}
+/** A list's items, with the note number each one holds. */
+function itemsOf(list) {
+	const start = Number(list[1].start ?? 1) || 1;
+	return childrenOf(list).filter((child) => isElement(child) && child[0] === "li").map((item, index) => ({
+		item,
+		note: start + index
+	}));
+}
+function notesOf(list, fence, uid, issues) {
+	const start = Number(list[1].start ?? 1) || 1;
+	const items = itemsOf(list);
+	const used = new Set([...fence.markers.values()].flat());
+	const known = new Set(items.map(({ note }) => note));
+	for (const note of [...used].sort((a, b) => a - b)) if (!known.has(note)) issues.push({
+		rule: "comark/code-notes/marker-without-note",
+		message: `${fence.name}: marker <${note}> has no note, since the list after it ${items.length === 1 ? "has 1 item" : `has ${items.length} items`}. Add its note, or remove the marker.`
+	});
+	for (const note of known) if (!used.has(note)) issues.push({
+		rule: "comark/code-notes/note-without-marker",
+		message: `${fence.name}: note ${note} has no <${note}> marker in the code. Add \`// <${note}>\` at the end of its line, in the language's comment.`
+	});
+	return [
+		NOTES_TAG,
+		start === 1 ? {} : { start },
+		...items.map(({ item, note }) => {
+			return [
+				"li",
+				{ id: `${uid}-${note}` },
+				used.has(note) ? ["a", {
+					class: "cn-marker",
+					href: `#${uid}-${note}-ref`,
+					"data-note": String(note),
+					"aria-label": `Back to marker ${note}`
+				}] : ["span", {
+					class: "cn-marker",
+					"data-note": String(note)
+				}],
+				[
+					"div",
+					{},
+					...childrenOf(item)
+				]
+			];
+		})
+	];
+}
+/**
+* Turns `// <1>` at the end of a line in a fence, in the language's comment, into a numbered marker, and the numbered
+* list right after the fence into its notes, each linked to its marker and back. Markers are stripped before Shiki
+* highlights the code and drawn into its lines after, so put this plugin after Comark's `shiki` in `plugins`.
+* Problems are added to `meta.issues`.
+*/
+var src_default = defineComarkPlugin(() => {
+	const parses = /* @__PURE__ */ new WeakMap();
+	return {
+		name: "comark-code-notes",
+		markdownItPost(state) {
+			parses.set(state, read(state.tokens));
+		},
+		post(state) {
+			const fences = parses.get(state) ?? [];
+			const { tree } = state;
+			const issues = [];
+			const names = (state.options.plugins ?? []).map((plugin) => plugin.name);
+			const shikiLater = names.indexOf("shiki") > names.indexOf("comark-code-notes");
+			let preOrder = 0;
+			const walk = (nodes, start) => {
+				for (let index = start; index < nodes.length; index++) {
+					const node = nodes[index];
+					if (!node || !isElement(node)) continue;
+					if (node[0] !== "pre") {
+						walk(node, 2);
+						continue;
+					}
+					preOrder++;
+					const fence = fences.find((candidate) => candidate.order === preOrder);
+					if (!fence || !fence.markers.size) continue;
+					if (!fence.notes) {
+						issues.push({
+							rule: "comark/code-notes/missing-notes",
+							message: `${fence.name} has markers like \`<1>\` but no numbered list right after it, so they stay in the code. Write the notes as a numbered list right after the fence.`
+						});
+						continue;
+					}
+					const next = nodes.findIndex((child, after) => after > index && isElement(child));
+					const list = nodes[next];
+					const code = childrenOf(node).find((child) => isElement(child) && child[0] === "code");
+					if (!list || !isElement(list) || list[0] !== "ol" || !code) continue;
+					const uid = `cn-${hash(`${fence.name}\n${fence.code}`)}`;
+					draw(code, fence, uid, new Set(itemsOf(list).map(({ note }) => note)));
+					nodes[next] = notesOf(list, fence, uid, issues);
+				}
+			};
+			walk(tree.nodes, 0);
+			if (shikiLater && fences.some((fence) => fence.notes)) issues.push({
+				rule: "comark/code-notes/shiki-order",
+				message: "Code notes: `shiki` comes after `comark-code-notes` in `plugins`, so the annotated code isn't highlighted. Put the code notes plugin after `shiki`."
+			});
+			tree.meta.issues = [...tree.meta.issues ?? [], ...issues.map((issue) => issue.message)];
+			tree.meta.issueRules = {
+				...tree.meta.issueRules,
+				...Object.fromEntries(issues.map((issue) => [issue.message, issue.rule]))
+			};
+		}
+	};
+});
+//#endregion
+export { NOTES_TAG, src_default as default };

package/dist/react.d.mts

@@ -0,0 +1,16 @@
+import _default, { CodeNotesAttributes, CodeNotesMeta, NOTES_TAG } from "./index.mjs";
+import { ReactNode } from "react";
+//#region src/react.d.ts
+/** The notes under an annotated fence, for `@comark/react`. */
+export declare function CodeNotes({ start, children }: CodeNotesAttributes & {
+  children?: ReactNode;
+}): import("react").DetailedReactHTMLElement<{
+  className: string;
+  start: number | undefined;
+}, HTMLElement>;
+/** Pass these as `components` to `@comark/react`. */
+export declare const components: {
+  CodeNotes: typeof CodeNotes;
+};
+//#endregion
+export { type CodeNotesAttributes, type CodeNotesMeta, NOTES_TAG, _default as default };

package/dist/react.mjs

@@ -0,0 +1,16 @@
+import src_default, { NOTES_TAG } from "./index.mjs";
+import { addStyles } from "./client.mjs";
+import { createElement, useEffect } from "react";
+//#region src/react.ts
+/** The notes under an annotated fence, for `@comark/react`. */
+function CodeNotes({ start, children }) {
+	useEffect(addStyles, []);
+	return createElement("ol", {
+		className: "cn-notes",
+		start: start && start !== 1 ? start : void 0
+	}, children);
+}
+/** Pass these as `components` to `@comark/react`. */
+const components = { CodeNotes };
+//#endregion
+export { CodeNotes, NOTES_TAG, components, src_default as default };

package/dist/style.css

@@ -0,0 +1 @@
+@layer comark{:where(.cn-marker,.cn-notes){--_comark-background:var(--comark-background,var(--ui-bg,var(--background,#fff)));--_comark-foreground:var(--comark-foreground,var(--ui-text-highlighted,var(--foreground,#0a0a0a)));--_comark-muted:var(--comark-muted,var(--ui-text-muted,var(--muted-foreground,#737373)));--_comark-border:var(--comark-border,var(--ui-border,var(--border,#e5e5e5)));--_comark-accent:var(--comark-accent,var(--ui-bg-elevated,var(--accent,#f5f5f5)));--_comark-ring:var(--comark-ring,var(--ui-primary,var(--ring,#a1a1a1)));--_comark-radius:var(--comark-radius,calc(var(--ui-radius,calc(var(--radius,.625rem)/2))*2));--_comark-font:var(--comark-font,var(--font-sans,ui-sans-serif,system-ui,sans-serif))}@media (prefers-color-scheme:dark){:where(.cn-marker,.cn-notes){--_comark-background:var(--comark-background,var(--ui-bg,var(--background,#0a0a0a)));--_comark-foreground:var(--comark-foreground,var(--ui-text-highlighted,var(--foreground,#fafafa)));--_comark-muted:var(--comark-muted,var(--ui-text-muted,var(--muted-foreground,#a1a1a1)));--_comark-border:var(--comark-border,var(--ui-border,var(--border,rgb(255 255 255/.1))));--_comark-accent:var(--comark-accent,var(--ui-bg-elevated,var(--accent,#262626)));--_comark-ring:var(--comark-ring,var(--ui-primary,var(--ring,#737373)))}}:where(.cn-marker){--cn-marker:var(--primary,var(--_comark-foreground));--cn-marker-text:var(--cn-marker)}.cn-marker{display:inline-flex;align-items:center;justify-content:center;box-sizing:border-box;min-width:1.25rem;height:1.25rem;margin-inline-start:.5rem;padding:0 .3rem;border-radius:999px;background:color-mix(in srgb,var(--cn-marker) 10%,var(--_comark-background));box-shadow:inset 0 0 0 1px color-mix(in srgb,var(--cn-marker) 22%,transparent);font:600 .6875rem/1 var(--_comark-font);font-variant-numeric:tabular-nums;vertical-align:.0625rem;user-select:none;transition:background-color .15s}.cn-marker{color:var(--cn-marker-text)!important;text-decoration:none!important;border:0!important}.cn-marker::after{content:attr(data-note)}a.cn-marker:hover{background:color-mix(in srgb,var(--cn-marker) 18%,var(--_comark-background))}a.cn-marker:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--_comark-ring) 50%,transparent)}.cn-marker:target{box-shadow:0 0 0 3px color-mix(in srgb,var(--_comark-ring) 60%,transparent)}.line:has(>.cn-marker:is(:target,:focus)){border-image:conic-gradient(color-mix(in srgb,var(--cn-marker,var(--primary,currentColor)) 14%,transparent) 0 0) fill 0//.25em 100vw}.cn-notes{margin:.75rem 0 1.5rem}.cn-notes{padding:0!important;list-style:none!important}.cn-notes>li{display:grid;grid-template-columns:auto minmax(0,1fr);align-items:baseline;gap:.625rem;margin:.375rem 0;padding:.125rem .375rem;border-radius:calc(var(--_comark-radius) - 4px)}.cn-notes>li>.cn-marker{margin:0}.cn-notes>li>div>:first-child{margin-top:0!important}.cn-notes>li>div>:last-child{margin-bottom:0!important}.cn-notes>li:target{background:var(--_comark-accent)}}

package/dist/styles-zxOi3Y7k.mjs

@@ -0,0 +1,83 @@
+//#region ../zoom/dist/theme.mjs
+const tokens = [
+	[
+		"background",
+		"ui-bg",
+		"background",
+		"#fff",
+		"#0a0a0a"
+	],
+	[
+		"foreground",
+		"ui-text-highlighted",
+		"foreground",
+		"#0a0a0a",
+		"#fafafa"
+	],
+	[
+		"muted",
+		"ui-text-muted",
+		"muted-foreground",
+		"#737373",
+		"#a1a1a1"
+	],
+	[
+		"border",
+		"ui-border",
+		"border",
+		"#e5e5e5",
+		"rgb(255 255 255/.1)"
+	],
+	[
+		"accent",
+		"ui-bg-elevated",
+		"accent",
+		"#f5f5f5",
+		"#262626"
+	],
+	[
+		"ring",
+		"ui-primary",
+		"ring",
+		"#a1a1a1",
+		"#737373"
+	]
+];
+const resolve = (scheme) => tokens.map((token) => `--_comark-${token[0]}:var(--comark-${token[0]},var(--${token[1]},var(--${token[2]},${token[scheme]})))`).join(";");
+/**
+* Resolves the `--comark-*` tokens on `selector`, falling back to Nuxt UI's variables, then shadcn/ui's, then shadcn's
+* neutral theme. Nuxt UI's corners are twice its `--ui-radius`, so the radius halves shadcn's to double it back.
+* They resolve on the component rather than `:root`, so a `.dark` class anywhere above it switches the theme, and a
+* `--comark-*` set on any ancestor still inherits down. `:where()` keeps them at zero specificity.
+*/
+function theme(selector) {
+	const where = `:where(${selector})`;
+	return `${where}{${resolve(3)};--_comark-radius:var(--comark-radius,calc(var(--ui-radius,calc(var(--radius,.625rem)/2))*2));--_comark-font:var(--comark-font,var(--font-sans,ui-sans-serif,system-ui,sans-serif))}@media (prefers-color-scheme:dark){${where}{${resolve(4)}}}`;
+}
+//#endregion
+//#region src/styles.ts
+/**
+* Round numbered markers at the ends of lines and before each note, as a soft tint of shadcn/ui's `--primary` when the
+* page has it, or of the foreground otherwise, with the number in that color, on the shared `--comark-*` tokens.
+* Override `--cn-marker` and `--cn-marker-text`. The number is drawn by CSS, so copying the code never takes it along.
+* The rules sit in the `comark` layer, so any unlayered rule of the host's wins.
+*/
+const css = `@layer comark{${[
+	theme(".cn-marker,.cn-notes"),
+	":where(.cn-marker){--cn-marker:var(--primary,var(--_comark-foreground));--cn-marker-text:var(--cn-marker)}",
+	".cn-marker{display:inline-flex;align-items:center;justify-content:center;box-sizing:border-box;min-width:1.25rem;height:1.25rem;margin-inline-start:.5rem;padding:0 .3rem;border-radius:999px;background:color-mix(in srgb,var(--cn-marker) 10%,var(--_comark-background));box-shadow:inset 0 0 0 1px color-mix(in srgb,var(--cn-marker) 22%,transparent);font:600 .6875rem/1 var(--_comark-font);font-variant-numeric:tabular-nums;vertical-align:.0625rem;user-select:none;transition:background-color .15s}",
+	".cn-marker{color:var(--cn-marker-text)!important;text-decoration:none!important;border:0!important}",
+	".cn-marker::after{content:attr(data-note)}",
+	"a.cn-marker:hover{background:color-mix(in srgb,var(--cn-marker) 18%,var(--_comark-background))}",
+	"a.cn-marker:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--_comark-ring) 50%,transparent)}",
+	".cn-marker:target{box-shadow:0 0 0 3px color-mix(in srgb,var(--_comark-ring) 60%,transparent)}",
+	".line:has(>.cn-marker:is(:target,:focus)){border-image:conic-gradient(color-mix(in srgb,var(--cn-marker,var(--primary,currentColor)) 14%,transparent) 0 0) fill 0//.25em 100vw}",
+	".cn-notes{margin:.75rem 0 1.5rem}",
+	".cn-notes{padding:0!important;list-style:none!important}",
+	".cn-notes>li{display:grid;grid-template-columns:auto minmax(0,1fr);align-items:baseline;gap:.625rem;margin:.375rem 0;padding:.125rem .375rem;border-radius:calc(var(--_comark-radius) - 4px)}",
+	".cn-notes>li>.cn-marker{margin:0}",
+	".cn-notes>li>div>:first-child{margin-top:0!important}.cn-notes>li>div>:last-child{margin-bottom:0!important}",
+	".cn-notes>li:target{background:var(--_comark-accent)}"
+].join("")}}`;
+//#endregion
+export { css as t };

package/dist/svelte/CodeNotes.svelte

@@ -0,0 +1,10 @@
+<!-- The notes under an annotated fence, for `@comark/svelte`. -->
+<script>
+  import { onMount } from "svelte";
+  import { addStyles } from "comark-code-notes/client";
+
+  let { start = undefined, children } = $props();
+  onMount(addStyles);
+</script>
+
+<ol class="cn-notes" start={start && start !== 1 ? start : undefined}>{@render children?.()}</ol>

package/dist/svelte/index.d.ts

@@ -0,0 +1,8 @@
+import type { Component, Snippet } from "svelte";
+import type { CodeNotesAttributes } from "comark-code-notes";
+
+export { default, NOTES_TAG } from "comark-code-notes";
+export type { CodeNotesAttributes, CodeNotesMeta } from "comark-code-notes";
+
+export declare const CodeNotes: Component<CodeNotesAttributes & { children?: Snippet }>;
+export declare const components: { CodeNotes: typeof CodeNotes };

package/dist/svelte/index.js

@@ -0,0 +1,6 @@
+// The notes under an annotated fence, for `@comark/svelte`. Pass `components` to it; the parse plugin comes from `comark-code-notes`.
+import CodeNotes from "./CodeNotes.svelte";
+
+export { default, NOTES_TAG } from "comark-code-notes";
+export { CodeNotes };
+export const components = { CodeNotes };

package/dist/vue.d.mts

@@ -0,0 +1,22 @@
+import _default, { CodeNotesAttributes, CodeNotesMeta, NOTES_TAG } from "./index.mjs";
+//#region src/vue.d.ts
+/** The notes under an annotated fence, for `@comark/vue`. */
+export declare const CodeNotes: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  start: NumberConstructor;
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  start: NumberConstructor;
+}>> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/** Pass these as `components` to `@comark/vue`. */
+export declare const components: {
+  CodeNotes: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    start: NumberConstructor;
+  }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    start: NumberConstructor;
+  }>> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+};
+//#endregion
+export { type CodeNotesAttributes, type CodeNotesMeta, NOTES_TAG, _default as default };

package/dist/vue.mjs

@@ -0,0 +1,21 @@
+import src_default, { NOTES_TAG } from "./index.mjs";
+import { addStyles } from "./client.mjs";
+import { defineComponent, h, onMounted } from "vue";
+//#region src/vue.ts
+/** The notes under an annotated fence, for `@comark/vue`. */
+const CodeNotes = defineComponent({
+	name: "CodeNotes",
+	inheritAttrs: false,
+	props: { start: Number },
+	setup(props, { slots }) {
+		onMounted(addStyles);
+		return () => h("ol", {
+			class: "cn-notes",
+			start: props.start && props.start !== 1 ? props.start : void 0
+		}, slots.default?.());
+	}
+});
+/** Pass these as `components` to `@comark/vue`. */
+const components = { CodeNotes };
+//#endregion
+export { CodeNotes, NOTES_TAG, components, src_default as default };

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "comark-code-notes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.1",
+  "description": "Numbered notes on lines of code: a // <1> marker in a fence links to the numbered list after it. A Comark plugin.",
+  "keywords": [
+    "annotations",
+    "callouts",
+    "code",
+    "comark",
+    "markdown",
+    "mdc",
+    "plugin",
+    "shiki"
+  ],
+  "homepage": "https://comark-ui.onmax.me/code-notes",
+  "bugs": "https://github.com/onmax/comark-ui/issues",
+  "license": "MIT",
+  "author": "onmax",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onmax/comark-ui.git",
+    "directory": "packages/code-notes"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./client": "./dist/client.mjs",
+    "./html": "./dist/html.mjs",
+    "./react": "./dist/react.mjs",
+    "./style.css": "./dist/style.css",
+    "./svelte": {
+      "types": "./dist/svelte/index.d.ts",
+      "svelte": "./dist/svelte/index.js",
+      "default": "./dist/svelte/index.js"
+    },
+    "./vue": "./dist/vue.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@comark/html": "^0.8.1",
+    "@comark/react": "^0.8.1",
+    "@comark/vue": "^0.8.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "comark": "^0.8.1",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "svelte": "^5.57.2",
+    "vue": "^3.5.44",
+    "comark-zoom": "0.7.1"
+  },
+  "peerDependencies": {
+    "@comark/html": "^0.8.0",
+    "comark": "^0.8.0",
+    "react": ">=18",
+    "svelte": ">=5",
+    "vue": ">=3.5"
+  },
+  "peerDependenciesMeta": {
+    "@comark/html": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "doctor": "vite-doctor . --no-cache --max-warnings 0 --format text"
+  }
 }