@mrsf/markdown-it-mrsf 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wictor Wilén
+
+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

@@ -0,0 +1,178 @@
+# @mrsf/markdown-it-mrsf
+
+A [markdown-it](https://github.com/markdown-it/markdown-it) plugin for rendering [MRSF (Sidemark)](https://github.com/wictorwilen/MRSF) review comments directly into HTML output.
+
+Renders badges, line highlights, inline text highlights, and tooltips — no client-side JavaScript required for static use. An optional interactive mode adds action buttons for host applications to hook into.
+
+## Install
+
+```bash
+npm install @mrsf/markdown-it-mrsf
+```
+
+## Browser & Bundler Support
+
+The plugin works seamlessly in both Node.js and browser environments. When bundled with tools like **Vite**, **webpack**, or **esbuild**, the `"browser"` export condition in `package.json` automatically resolves to a browser-safe entry point — no special imports required.
+
+```ts
+// Works everywhere — Node.js, Vite, webpack, etc.
+import { mrsfPlugin } from "@mrsf/markdown-it-mrsf";
+```
+
+In browser environments, only the `comments` and `loader` options are available (no file-system access). The `sidecarPath` and `documentPath` options require Node.js.
+
+## Usage
+
+### Inline data (recommended for testing and custom pipelines)
+
+```ts
+import MarkdownIt from "markdown-it";
+import { mrsfPlugin } from "@mrsf/markdown-it-mrsf";
+
+const md = new MarkdownIt();
+md.use(mrsfPlugin, {
+  comments: {
+    mrsf_version: "1.0",
+    document: "guide.md",
+    comments: [
+      {
+        id: "c1",
+        author: "Jane",
+        timestamp: "2026-01-01T00:00:00Z",
+        text: "Can you clarify this section?",
+        resolved: false,
+        line: 3,
+      },
+    ],
+  },
+});
+
+const html = md.render(markdownSource);
+```
+
+### Auto-discover from disk
+
+```ts
+md.use(mrsfPlugin, {
+  documentPath: "docs/guide.md",
+});
+```
+
+The plugin looks for `docs/guide.md.review.yaml` (or `.review.json`) next to the document.
+
+### Explicit sidecar path
+
+```ts
+md.use(mrsfPlugin, {
+  sidecarPath: ".reviews/docs/guide.md.review.yaml",
+});
+```
+
+### Custom loader function
+
+```ts
+md.use(mrsfPlugin, {
+  loader: () => {
+    // Load sidecar data however you like — from a database, API, in-memory store, etc.
+    return {
+      mrsf_version: "1.0",
+      document: "guide.md",
+      comments: [/* ... */],
+    };
+  },
+});
+```
+
+## Stylesheet
+
+Include the default CSS for badges, tooltips, and highlights:
+
+```ts
+import "@mrsf/markdown-it-mrsf/style.css";
+```
+
+Or link directly in HTML:
+
+```html
+<link rel="stylesheet" href="node_modules/@mrsf/markdown-it-mrsf/dist/style.css">
+```
+
+Customise with CSS custom properties:
+
+```css
+:root {
+  --mrsf-accent: #3794ff;
+  --mrsf-badge-bg: #007acc;
+  --mrsf-badge-fg: #fff;
+  --mrsf-tooltip-bg: #252526;
+  --mrsf-tooltip-fg: #cccccc;
+  --mrsf-highlight-bg: rgba(255, 213, 79, 0.25);
+}
+```
+
+## Interactive Mode
+
+Enable `interactive: true` to add action buttons (Resolve, Reply, Edit) inside tooltips. These render as `<button data-mrsf-action="..." data-mrsf-comment-id="...">` elements — inert without JavaScript.
+
+```ts
+md.use(mrsfPlugin, {
+  comments: sidecarData,
+  interactive: true,
+});
+```
+
+### Controller
+
+Include the optional controller to dispatch custom events when action buttons are clicked:
+
+```ts
+import "@mrsf/markdown-it-mrsf/controller";
+
+document.addEventListener("mrsf:resolve", (e) => {
+  console.log("Resolve comment:", e.detail.commentId);
+});
+
+document.addEventListener("mrsf:reply", (e) => {
+  console.log("Reply to:", e.detail.commentId);
+});
+```
+
+Events dispatched: `mrsf:resolve`, `mrsf:unresolve`, `mrsf:reply`, `mrsf:edit`, `mrsf:navigate`.
+
+Each event's `detail` contains `{ commentId: string, line: number | null, action: string }`.
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `comments` | `MrsfDocument` | — | Pre-loaded sidecar data (highest priority) |
+| `loader` | `() => MrsfDocument \| null` | — | Custom loader function for sidecar data |
+| `documentPath` | `string` | — | Path to Markdown file for auto-discovery |
+| `sidecarPath` | `string` | — | Explicit path to sidecar file |
+| `showResolved` | `boolean` | `true` | Whether to show resolved comments |
+| `interactive` | `boolean` | `false` | Add action buttons for host JS integration |
+| `gutterPosition` | `'left' \| 'tight' \| 'right'` | `'right'` | Badge position: left margin gutter, tight (before text), or floated right |
+| `gutterForInline` | `boolean` | `true` | Show gutter badge for comments that also have inline highlights |
+| `inlineHighlights` | `boolean` | `true` | Render inline text highlights for `selected_text` |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Color scheme hint |
+| `cwd` | `string` | `process.cwd()` | Working directory for file resolution |
+
+### Display Modes
+
+The plugin supports several display modes that can be combined:
+
+- **Gutter + inline** (default): Badges appear in the gutter, `selected_text` is highlighted inline with hover tooltips on both.
+- **Gutter only** (`inlineHighlights: false`): Only gutter badges shown, no inline highlights.
+- **Inline only** (`gutterForInline: false`): Lines with inline-highlighted comments show only the highlight (with tooltip) — no gutter badge. Lines without `selected_text` still show badges.
+
+## DOM Contract
+
+All rendered elements follow a strict data-attribute contract:
+
+- `data-mrsf-line` — source line number (1-based)
+- `data-mrsf-comment-id` — comment identifier
+- `data-mrsf-action` — action type (`resolve`, `unresolve`, `reply`, `edit`, `navigate`)
+
+## License
+
+[MIT](../LICENSE)

package/dist/browser.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Browser-safe entry point for @mrsf/markdown-it-mrsf.
+ *
+ * This entry is automatically selected by bundlers (Vite, webpack, esbuild)
+ * via the `"browser"` export condition in package.json. It supports the
+ * `comments` and `loader` provisioning modes — no Node.js file-system APIs.
+ *
+ * You do NOT need to import this directly. Just use:
+ *   import { mrsfPlugin } from "@mrsf/markdown-it-mrsf";
+ *
+ * Your bundler will resolve to this file automatically when targeting
+ * a browser environment.
+ */
+import type { MrsfPluginOptions } from "./types.js";
+export type { MrsfPluginOptions, SlimComment, CommentThread, LineMap } from "./types.js";
+/**
+ * The markdown-it plugin function (browser-safe).
+ *
+ * Supports `comments` (inline data) and `loader` (custom function) options.
+ */
+export declare const mrsfPlugin: (md: import("markdown-it").default, options?: MrsfPluginOptions) => void;
+export default mrsfPlugin;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.js

@@ -0,0 +1,39 @@
+/**
+ * Browser-safe entry point for @mrsf/markdown-it-mrsf.
+ *
+ * This entry is automatically selected by bundlers (Vite, webpack, esbuild)
+ * via the `"browser"` export condition in package.json. It supports the
+ * `comments` and `loader` provisioning modes — no Node.js file-system APIs.
+ *
+ * You do NOT need to import this directly. Just use:
+ *   import { mrsfPlugin } from "@mrsf/markdown-it-mrsf";
+ *
+ * Your bundler will resolve to this file automatically when targeting
+ * a browser environment.
+ */
+import { createMrsfPlugin } from "./shared.js";
+/**
+ * The markdown-it plugin function (browser-safe).
+ *
+ * Supports `comments` (inline data) and `loader` (custom function) options.
+ */
+export const mrsfPlugin = createMrsfPlugin((options) => {
+    if (options.comments) {
+        return options.comments;
+    }
+    if (options.loader) {
+        try {
+            return options.loader();
+        }
+        catch {
+            return null;
+        }
+    }
+    if (options.sidecarPath || options.documentPath) {
+        console.warn("[@mrsf/markdown-it-mrsf] sidecarPath and documentPath require Node.js. " +
+            "Use `comments` or `loader` options in browser environments.");
+    }
+    return null;
+});
+export default mrsfPlugin;
+//# sourceMappingURL=browser.js.map

package/dist/controller.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Sidemark — Client-side event controller for interactive mode.
+ *
+ * Optional module that listens for clicks on `[data-mrsf-action]` elements
+ * and dispatches CustomEvents on the document for host applications.
+ *
+ * Usage (ESM):
+ *   import "@mrsf/markdown-it-mrsf/controller";
+ *
+ * Usage (script tag):
+ *   <script src=".../@mrsf/markdown-it-mrsf/dist/controller.js"></script>
+ *
+ * Events dispatched:
+ *   - mrsf:resolve   { commentId, line }
+ *   - mrsf:unresolve { commentId, line }
+ *   - mrsf:reply     { commentId, line }
+ *   - mrsf:edit      { commentId, line }
+ *   - mrsf:navigate  { commentId, line }
+ */
+export type MrsfAction = "resolve" | "unresolve" | "reply" | "edit" | "navigate";
+export interface MrsfActionDetail {
+    commentId: string;
+    line: number | null;
+    action: MrsfAction;
+}
+//# sourceMappingURL=controller.d.ts.map

package/dist/controller.js

@@ -0,0 +1,40 @@
+/**
+ * Sidemark — Client-side event controller for interactive mode.
+ *
+ * Optional module that listens for clicks on `[data-mrsf-action]` elements
+ * and dispatches CustomEvents on the document for host applications.
+ *
+ * Usage (ESM):
+ *   import "@mrsf/markdown-it-mrsf/controller";
+ *
+ * Usage (script tag):
+ *   <script src=".../@mrsf/markdown-it-mrsf/dist/controller.js"></script>
+ *
+ * Events dispatched:
+ *   - mrsf:resolve   { commentId, line }
+ *   - mrsf:unresolve { commentId, line }
+ *   - mrsf:reply     { commentId, line }
+ *   - mrsf:edit      { commentId, line }
+ *   - mrsf:navigate  { commentId, line }
+ */
+function init() {
+    document.addEventListener("click", (e) => {
+        const target = e.target.closest("[data-mrsf-action]");
+        if (!target)
+            return;
+        const action = target.dataset.mrsfAction;
+        const commentId = target.dataset.mrsfCommentId;
+        if (!action || !commentId)
+            return;
+        const lineStr = target.dataset.mrsfLine;
+        const line = lineStr ? parseInt(lineStr, 10) : null;
+        e.preventDefault();
+        e.stopPropagation();
+        const detail = { commentId, line, action };
+        document.dispatchEvent(new CustomEvent(`mrsf:${action}`, { detail, bubbles: true }));
+    });
+}
+// Auto-initialize
+init();
+export {};
+//# sourceMappingURL=controller.js.map

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @mrsf/markdown-it-mrsf — markdown-it plugin for MRSF review comments.
+ *
+ * This is the full-featured Node.js entry point. It supports all four
+ * sidecar provisioning modes: `comments`, `loader`, `sidecarPath`, and
+ * `documentPath`. The latter two require Node.js file-system APIs.
+ *
+ * In browser / bundler environments, the `"browser"` export condition in
+ * package.json automatically resolves to the browser-safe entry, so you
+ * never need to import a different path — just use:
+ *
+ * @example
+ * ```ts
+ * import MarkdownIt from "markdown-it";
+ * import { mrsfPlugin } from "@mrsf/markdown-it-mrsf";
+ *
+ * const md = new MarkdownIt();
+ * md.use(mrsfPlugin, { documentPath: "docs/guide.md" });
+ * const html = md.render(markdownSource);
+ * ```
+ */
+import type { MrsfPluginOptions } from "./types.js";
+export type { MrsfPluginOptions, SlimComment, CommentThread, LineMap } from "./types.js";
+export type { MrsfAction, MrsfActionDetail } from "./controller.js";
+/**
+ * The markdown-it plugin function (Node.js — full feature set).
+ */
+export declare const mrsfPlugin: (md: import("markdown-it").default, options?: MrsfPluginOptions) => void;
+export default mrsfPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,87 @@
+/**
+ * @mrsf/markdown-it-mrsf — markdown-it plugin for MRSF review comments.
+ *
+ * This is the full-featured Node.js entry point. It supports all four
+ * sidecar provisioning modes: `comments`, `loader`, `sidecarPath`, and
+ * `documentPath`. The latter two require Node.js file-system APIs.
+ *
+ * In browser / bundler environments, the `"browser"` export condition in
+ * package.json automatically resolves to the browser-safe entry, so you
+ * never need to import a different path — just use:
+ *
+ * @example
+ * ```ts
+ * import MarkdownIt from "markdown-it";
+ * import { mrsfPlugin } from "@mrsf/markdown-it-mrsf";
+ *
+ * const md = new MarkdownIt();
+ * md.use(mrsfPlugin, { documentPath: "docs/guide.md" });
+ * const html = md.render(markdownSource);
+ * ```
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseSidecarContent } from "@mrsf/cli";
+import { createMrsfPlugin } from "./shared.js";
+/**
+ * The markdown-it plugin function (Node.js — full feature set).
+ */
+export const mrsfPlugin = createMrsfPlugin((options) => {
+    // Priority 1: inline data
+    if (options.comments) {
+        return options.comments;
+    }
+    // Priority 2: custom loader function
+    if (options.loader) {
+        try {
+            return options.loader();
+        }
+        catch {
+            return null;
+        }
+    }
+    // Priority 3: explicit sidecar path
+    if (options.sidecarPath) {
+        try {
+            const abs = path.resolve(options.cwd || process.cwd(), options.sidecarPath);
+            const content = readFileSync(abs, "utf-8");
+            return parseSidecarContent(content, abs);
+        }
+        catch {
+            return null;
+        }
+    }
+    // Priority 4: auto-discover from documentPath
+    if (options.documentPath) {
+        try {
+            const cwd = options.cwd || process.cwd();
+            const abs = path.resolve(cwd, options.documentPath);
+            const yamlPath = abs + ".review.yaml";
+            const jsonPath = abs + ".review.json";
+            let raw = null;
+            let hint = null;
+            try {
+                raw = readFileSync(yamlPath, "utf-8");
+                hint = yamlPath;
+            }
+            catch {
+                try {
+                    raw = readFileSync(jsonPath, "utf-8");
+                    hint = jsonPath;
+                }
+                catch {
+                    return null;
+                }
+            }
+            if (!raw)
+                return null;
+            return parseSidecarContent(raw, hint);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+});
+export default mrsfPlugin;
+//# sourceMappingURL=index.js.map

package/dist/rules/core.d.ts

@@ -0,0 +1,27 @@
+/**
+ * MRSF markdown-it plugin — core rule.
+ *
+ * Walks the parsed token stream and injects `mrsf_badge` tokens
+ * at lines that have comments, and wraps `selected_text` matches
+ * with `mrsf_highlight_open`/`close` tokens (with tooltip metadata).
+ */
+import type StateCore from "markdown-it/lib/rules_core/state_core.mjs";
+import type { LineMap } from "../types.js";
+/** Options forwarded from the plugin to the core rule. */
+export interface CoreOptions {
+    interactive: boolean;
+    gutterPosition: "left" | "tight" | "right";
+    gutterForInline: boolean;
+    inlineHighlights: boolean;
+}
+/**
+ * Install the MRSF core rule on a markdown-it instance.
+ */
+export declare function installCoreRule(md: {
+    core: {
+        ruler: {
+            push: (name: string, fn: (state: StateCore) => void) => void;
+        };
+    };
+}, lineMap: LineMap, options: CoreOptions): void;
+//# sourceMappingURL=core.d.ts.map

package/dist/rules/core.js

@@ -0,0 +1,149 @@
+/**
+ * MRSF markdown-it plugin — core rule.
+ *
+ * Walks the parsed token stream and injects `mrsf_badge` tokens
+ * at lines that have comments, and wraps `selected_text` matches
+ * with `mrsf_highlight_open`/`close` tokens (with tooltip metadata).
+ */
+/**
+ * Find the token index for a given 1-based source line.
+ * markdown-it tokens use `token.map = [startLine, endLine]` (0-based).
+ */
+function findTokenIndexForLine(tokens, line) {
+    const line0 = line - 1; // convert to 0-based
+    for (let i = 0; i < tokens.length; i++) {
+        const map = tokens[i].map;
+        if (map && map[0] <= line0 && line0 < map[1]) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Wrap occurrences of `text` inside inline token children with
+ * highlight open/close tokens. Stores thread data on the tokens
+ * so the renderer can produce an inline tooltip.
+ */
+function highlightInlineText(token, thread, interactive, Token) {
+    if (!token.children)
+        return false;
+    const text = thread.comment.selected_text;
+    if (!text)
+        return false;
+    const trimmed = text.trim();
+    if (!trimmed)
+        return false;
+    for (let i = 0; i < token.children.length; i++) {
+        const child = token.children[i];
+        if (child.type !== "text")
+            continue;
+        const idx = child.content.indexOf(trimmed);
+        if (idx === -1)
+            continue;
+        // Split the text token into: before + highlight_open + matched + highlight_close + after
+        const newTokens = [];
+        // Text before match
+        if (idx > 0) {
+            const before = new Token("text", "", 0);
+            before.content = child.content.slice(0, idx);
+            newTokens.push(before);
+        }
+        // Highlight open — carries thread metadata for inline tooltip
+        const open = new Token("mrsf_highlight_open", "mark", 1);
+        open.attrSet("class", "mrsf-highlight");
+        open.attrSet("data-mrsf-comment-id", thread.comment.id);
+        open.meta = { thread };
+        newTokens.push(open);
+        // Matched text
+        const matched = new Token("text", "", 0);
+        matched.content = trimmed;
+        newTokens.push(matched);
+        // Highlight close — carries thread metadata for inline tooltip
+        const close = new Token("mrsf_highlight_close", "mark", -1);
+        close.meta = { thread, interactive };
+        newTokens.push(close);
+        // Text after match
+        if (idx + trimmed.length < child.content.length) {
+            const after = new Token("text", "", 0);
+            after.content = child.content.slice(idx + trimmed.length);
+            newTokens.push(after);
+        }
+        // Replace the original child with our new tokens
+        token.children.splice(i, 1, ...newTokens);
+        return true;
+    }
+    return false;
+}
+/**
+ * Install the MRSF core rule on a markdown-it instance.
+ */
+export function installCoreRule(md, lineMap, options) {
+    const { interactive, gutterPosition, gutterForInline, inlineHighlights } = options;
+    md.core.ruler.push("mrsf_inject", (state) => {
+        const tokens = state.tokens;
+        const TokenCtor = state.Token;
+        // Track which lines we've already processed (to avoid double-injection
+        // when multiple tokens share the same source line).
+        const processed = new Set();
+        // We iterate backwards so that inserting tokens doesn't shift indices
+        // for tokens we haven't visited yet.
+        for (let i = tokens.length - 1; i >= 0; i--) {
+            const token = tokens[i];
+            const map = token.map;
+            if (!map)
+                continue;
+            // Skip inline tokens — they share the same map as their parent block.
+            // We must process the parent block (paragraph_open, heading_open, etc.)
+            // so the badge and class land on the correct rendered element.
+            if (token.type === "inline")
+                continue;
+            // Check each line in this token's range for comments
+            for (let line0 = map[0]; line0 < map[1]; line0++) {
+                const line = line0 + 1; // 1-based
+                if (processed.has(line))
+                    continue;
+                const threads = lineMap.get(line);
+                if (!threads || threads.length === 0)
+                    continue;
+                processed.add(line);
+                // Add line-highlight class to the block token
+                const existingClass = token.attrGet("class") || "";
+                token.attrSet("class", existingClass
+                    ? `${existingClass} mrsf-line-highlight`
+                    : "mrsf-line-highlight");
+                token.attrSet("data-mrsf-line", String(line));
+                // Determine whether all threads on this line have inline highlights
+                const allHaveInline = inlineHighlights &&
+                    threads.every((t) => !!t.comment.selected_text);
+                // Inject badge unless gutterForInline is false AND all threads are inline-highlighted
+                const showBadge = gutterForInline || !allHaveInline || !inlineHighlights;
+                if (showBadge) {
+                    const badgeToken = new TokenCtor("mrsf_badge", "", 0);
+                    badgeToken.meta = { line, threads, interactive, gutterPosition };
+                    tokens.splice(i + 1, 0, badgeToken);
+                }
+                // Highlight selected_text in the following inline token
+                if (inlineHighlights) {
+                    const offset = showBadge ? 2 : 1;
+                    const inlineAfter = tokens[i + offset];
+                    if (inlineAfter && inlineAfter.type === "inline") {
+                        for (const thread of threads) {
+                            if (thread.comment.selected_text) {
+                                highlightInlineText(inlineAfter, thread, interactive, TokenCtor);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // Wrap the entire output in a gutter container when using left gutter
+        if (gutterPosition === "left" && processed.size > 0) {
+            const openToken = new TokenCtor("mrsf_gutter_open", "div", 1);
+            openToken.attrSet("class", "mrsf-gutter-container");
+            tokens.unshift(openToken);
+            const closeToken = new TokenCtor("mrsf_gutter_close", "div", -1);
+            tokens.push(closeToken);
+        }
+    });
+}
+//# sourceMappingURL=core.js.map

package/dist/rules/renderer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * MRSF markdown-it plugin — renderer rules.
+ *
+ * Adds custom renderer rules for MRSF tokens:
+ *   - mrsf_badge: renders badge + tooltip HTML (gutter)
+ *   - mrsf_highlight_open/close: renders <mark> wrappers with inline tooltips
+ */
+/**
+ * Install MRSF renderer rules on a markdown-it instance.
+ */
+export declare function installRendererRules(md: {
+    renderer: {
+        rules: Record<string, ((...args: any[]) => string) | undefined>;
+    };
+}): void;
+//# sourceMappingURL=renderer.d.ts.map