@riebeckite/plugin-code-annotations 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright Rerurate_514
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,137 @@
+# @riebeckite/plugin-code-annotations
+
+VitePress/Docusaurus-style code block annotations: line highlighting, focus,
+and diff markers that work on plain `<pre><code>` blocks and on the line
+wrappers produced by `@riebeckite/plugin-code-enhance`.
+
+[日本語](./README_ja.md)
+
+## Installation
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { codeAnnotations } from "@riebeckite/plugin-code-annotations";
+
+export default defineConfig({
+  // ...
+  plugins: [codeAnnotations()],
+});
+```
+
+The plugin registers its own `style.css`. It adds no client entry and no
+runtime JavaScript.
+
+## Syntax
+
+### Line highlighting (fence meta)
+
+Add a brace range after the language, exactly like Docusaurus and VitePress.
+
+````md
+```js {2,4-5}
+const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;
+const e = 5;
+```
+````
+
+Lines `2`, `4`, and `5` receive `rb-code__line--highlighted`.
+
+### Focus
+
+Use the `focus` meta group, or an inline `[!code focus]` marker. An optional
+count focuses the current line and the following lines.
+
+````md
+```js focus:{2}
+const a = 1;
+const b = 2;
+```
+````
+
+````md
+```js
+const a = 1; // [!code focus]
+const b = 2;
+```
+````
+
+`.rb-code__line--focused` is applied. `[!code focus:3]` focuses three lines
+starting at the marker.
+
+### Diff
+
+````md
+```js
+const kept = true;
+const added = true;    // [!code ++]
+const removed = false; // [!code --]
+```
+````
+
+The marker comment is removed from the rendered text, and the line receives
+`rb-code__line--added` or `rb-code__line--removed`.
+
+### Explicit highlight marker
+
+````md
+```js
+const value = 1; // [!code highlight]
+```
+````
+
+Marker comments are recognized with the `//`, `#`, `--`, and `<!-- -->`
+comment prefixes, so the same syntax works for JavaScript, shell, SQL, Lua,
+HTML, and other languages.
+
+## Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `className` | `string` | `"rb-code"` | Class on the block root (`<pre>` or `rehype-pretty-code` `<figure>`) |
+| `lineClassName` | `string` | `"rb-code__line"` | Class on generated line wrappers |
+| `highlightClassName` | `string` | `"rb-code__line--highlighted"` | Class for highlighted lines |
+| `addedClassName` | `string` | `"rb-code__line--added"` | Class for `[!code ++]` lines |
+| `removedClassName` | `string` | `"rb-code__line--removed"` | Class for `[!code --]` lines |
+| `focusClassName` | `string` | `"rb-code__line--focused"` | Class for focused lines |
+| `language` | `string` | unset | Only annotate blocks of this language |
+
+```ts
+codeAnnotations({ highlightClassName: "is-highlighted" });
+```
+
+## Using with code-enhance
+
+`@riebeckite/plugin-code-annotations` does not import or depend on
+`@riebeckite/plugin-code-enhance`. It detects both raw `<pre><code>` text and
+the `.line` wrappers emitted by `rehype-pretty-code`:
+
+- If line wrappers already exist, their classes are extended in place and the
+  existing `data-line` attribute is kept.
+- Otherwise the plugin wraps the raw code text into
+  `<span class="rb-code__line" data-line="N">` elements.
+
+Because `rehype-pretty-code` substitutes the `<code>` element, the plan is also
+mirrored into the preserved fence meta, so annotations still apply after
+code-enhance runs. Place `codeAnnotations()` after `codeEnhance()` in the
+plugins array; the plugin uses `order: 10` to run after code-enhance's
+highlighting regardless.
+
+## Exports
+
+- `codeAnnotations(options?)` / `codeAnnotationsPlugin(options?)` — plugin factory
+- `remarkCodeAnnotations(options?)` — remark transform
+- `rehypeCodeAnnotations(options?)` — rehype transform
+- `parseCodeAnnotations(meta)` — parse fence meta into a plan
+- `parseLineRanges(spec)` — parse `1,3-5` into line numbers
+- `collectCodeAnnotations(meta, code)` — parse meta plus inline markers
+- `resolveCodeAnnotationsOptions(options?)` — fill in defaults
+- Types: `CodeAnnotationsOptions`, `ResolvedCodeAnnotationsOptions`,
+  `CodeAnnotationPlan`, `CodeAnnotationKind`
+
+## See also
+
+- [Plugin guide](../../docs/plugins_en.md)
+- [`@riebeckite/plugin-code-enhance`](../code-enhance/README.md)

package/README_ja.md

@@ -0,0 +1,136 @@
+# @riebeckite/plugin-code-annotations
+
+VitePress / Docusaurus 風のコードブロック装飾を加えるプラグインです。フェンスの
+メタ情報による行の強調と、`[!code ...]` のインラインマーカーによるフォーカス・
+差分表示に対応します。素の `<pre><code>` と
+`@riebeckite/plugin-code-enhance` の行ラッパーの両方で動作します。
+
+[English](./README.md)
+
+## 設定
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { codeAnnotations } from "@riebeckite/plugin-code-annotations";
+
+export default defineConfig({
+  // ...
+  plugins: [codeAnnotations()],
+});
+```
+
+プラグインは `style.css` のみを登録します。クライアントエントリーはなく、
+実行時 JavaScript は追加しません。
+
+## 書き方
+
+### フェンスメタによる行の強調
+
+言語の後ろに波括弧で行範囲を書きます。Docusaurus や VitePress と同じ記法です。
+
+````md
+```js {2,4-5}
+const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;
+const e = 5;
+```
+````
+
+2、4、5 行目に `rb-code__line--highlighted` が付きます。
+
+### フォーカス
+
+`focus` メタ、またはインラインの `[!code focus]` を使います。行数を指定すると
+その行から続く行までをまとめてフォーカスします。
+
+````md
+```js focus:{2}
+const a = 1;
+const b = 2;
+```
+````
+
+````md
+```js
+const a = 1; // [!code focus]
+const b = 2;
+```
+````
+
+`rb-code__line--focused` が付きます。`[!code focus:3]` なら 3 行分です。
+
+### 差分
+
+````md
+```js
+const kept = true;
+const added = true;    // [!code ++]
+const removed = false; // [!code --]
+```
+````
+
+マーカーのコメントは表示テキストから取り除かれ、行には
+`rb-code__line--added` または `rb-code__line--removed` が付きます。
+
+### 明示的な強調マーカー
+
+````md
+```js
+const value = 1; // [!code highlight]
+```
+````
+
+マーカーは `//`、`#`、`--`、`<!-- -->` のコメント記法に対応します。JavaScript、
+シェル、SQL、Lua、HTML などで同じ書き方が使えます。
+
+## オプション
+
+| オプション | 既定値 | 内容 |
+| --- | --- | --- |
+| `className` | `"rb-code"` | ブロック直下（`<pre>` または `rehype-pretty-code` の `<figure>`）に付くクラス |
+| `lineClassName` | `"rb-code__line"` | 生成する行ラッパーのクラス |
+| `highlightClassName` | `"rb-code__line--highlighted"` | 強調行のクラス |
+| `addedClassName` | `"rb-code__line--added"` | `[!code ++]` 行のクラス |
+| `removedClassName` | `"rb-code__line--removed"` | `[!code --]` 行のクラス |
+| `focusClassName` | `"rb-code__line--focused"` | フォーカス行のクラス |
+| `language` | 未設定 | 指定した言語のブロックだけを対象にする |
+
+```ts
+codeAnnotations({ highlightClassName: "is-highlighted" });
+```
+
+## code-enhance との併用
+
+`@riebeckite/plugin-code-annotations` は
+`@riebeckite/plugin-code-enhance` を import せず、依存もしません。素の
+`<pre><code>` のテキストと、`rehype-pretty-code` が出力する `.line` ラッパーの
+両方を検出します。
+
+- 行ラッパーがすでにある場合は、既存のクラスに追記し、既存の `data-line` を
+  そのまま使います。
+- ない場合は、コード本文を
+  `<span class="rb-code__line" data-line="N">` に分割します。
+
+`rehype-pretty-code` は `<code>` 要素を差し替えるため、注釈プランは保持される
+フェンスメタにも複製します。これにより code-enhance の後でも注釈が適用されます。
+プラグイン配列では `codeEnhance()` の後に `codeAnnotations()` を置いてください。
+`order: 10` により、順序に関わらず強調処理の後に実行されます。
+
+## 公開 API
+
+- `codeAnnotations(options?)` / `codeAnnotationsPlugin(options?)` — プラグインファクトリ
+- `remarkCodeAnnotations(options?)` — remark 変換
+- `rehypeCodeAnnotations(options?)` — rehype 変換
+- `parseCodeAnnotations(meta)` — フェンスメタをプランに変換
+- `parseLineRanges(spec)` — `1,3-5` を行番号に変換
+- `collectCodeAnnotations(meta, code)` — メタとインラインマーカーをまとめて解析
+- `resolveCodeAnnotationsOptions(options?)` — 既定値を補完
+- 型: `CodeAnnotationsOptions`、`ResolvedCodeAnnotationsOptions`、
+  `CodeAnnotationPlan`、`CodeAnnotationKind`
+
+## 関連資料
+
+- [プラグインシステム](../../../docs/ja/plugin-system.md)
+- [`@riebeckite/plugin-code-enhance`](../code-enhance/README_ja.md)

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { CodeAnnotationsOptions } from "./src/types.js";
+export { ANNOTATIONS_META_PREFIX, collectCodeAnnotations, createEmptyPlan, deserializeAnnotations, encodeAnnotationsMeta, extractAnnotationsMeta, hasAnnotations, parseCodeAnnotations, parseLineRanges, serializeAnnotations, stripInlineCodeAnnotation, } from "./src/annotations.js";
+export type { CollectedCodeAnnotations, InlineCodeAnnotation, } from "./src/annotations.js";
+export { rehypeCodeAnnotations } from "./src/rehype.js";
+export { remarkCodeAnnotations } from "./src/remark.js";
+export { DEFAULT_CODE_ANNOTATIONS_OPTIONS, resolveCodeAnnotationsOptions, } from "./src/options.js";
+export type { CodeAnnotationKind, CodeAnnotationPlan, CodeAnnotationsOptions, ResolvedCodeAnnotationsOptions, } from "./src/types.js";
+/**
+ * VitePress/Docusaurus-style code block annotations: line highlighting from
+ * fence meta and inline `[!code ...]` marker comments for focus, highlight,
+ * and diff lines.
+ *
+ * Runs after `@riebeckite/plugin-code-enhance` (via `order`) so it can annotate
+ * the line wrappers produced by `rehype-pretty-code` instead of re-wrapping
+ * them. It never imports or depends on code-enhance.
+ */
+export declare function codeAnnotations(options?: CodeAnnotationsOptions): import("@riebeckite/core").RiebeckitePlugin<import("./index.js").ResolvedCodeAnnotationsOptions>;
+export declare const codeAnnotationsPlugin: typeof codeAnnotations;

package/dist/index.js

@@ -0,0 +1,449 @@
+// index.ts
+import { createStyleAsset, definePlugin } from "@riebeckite/core";
+
+// src/annotations.ts
+var ANNOTATIONS_META_PREFIX = "rb-annotations=";
+var ANNOTATION_KEYS = [
+  "highlight",
+  "added",
+  "removed",
+  "focus"
+];
+var FOCUS_META_PATTERN = /(?:^|\s)focus[:=]\{([^}]*)\}/g;
+var HIGHLIGHT_META_PATTERN = /\{([^{}]*)\}/g;
+var INLINE_ANNOTATION_PATTERN = /([ \t]*)(?:(?:\/\/|#|--)[ \t]*\[!code[ \t]+(focus|highlight|\+\+|--)(?::(\d+))?\]|<!--[ \t]*\[!code[ \t]+(focus|highlight|\+\+|--)(?::(\d+))?[ \t]*-->)[ \t]*$/;
+function createEmptyPlan() {
+  return { highlight: [], added: [], removed: [], focus: [] };
+}
+function parseCodeAnnotations(meta) {
+  const plan = createEmptyPlan();
+  if (typeof meta !== "string" || meta.length === 0) return plan;
+  const rest = meta.replace(FOCUS_META_PATTERN, (_match, body) => {
+    addRanges(plan.focus, parseLineRanges(body));
+    return " ";
+  });
+  for (const match of rest.matchAll(HIGHLIGHT_META_PATTERN)) {
+    addRanges(plan.highlight, parseLineRanges(match[1] ?? ""));
+  }
+  return normalizePlan(plan);
+}
+function parseLineRanges(spec) {
+  const lines = [];
+  for (const part of spec.split(",")) {
+    const trimmed = part.trim();
+    if (trimmed === "") continue;
+    const range = /^(\d+)\s*-\s*(\d+)$/.exec(trimmed);
+    if (range) {
+      const first = Number(range[1]);
+      const second = Number(range[2]);
+      const from = Math.min(first, second);
+      const to = Math.max(first, second);
+      for (let line = from; line <= to; line += 1) lines.push(line);
+      continue;
+    }
+    if (/^\d+$/.test(trimmed)) lines.push(Number(trimmed));
+  }
+  return lines;
+}
+function stripInlineCodeAnnotation(line) {
+  const match = INLINE_ANNOTATION_PATTERN.exec(line);
+  if (!match) return { line, annotation: null };
+  const kind = normalizeKind(match[2] ?? match[4]);
+  if (!kind) return { line, annotation: null };
+  const rawCount = match[3] ?? match[5];
+  const parsedCount = rawCount === void 0 ? 1 : Number(rawCount);
+  const lineCount = Number.isFinite(parsedCount) ? Math.max(1, parsedCount) : 1;
+  const index = match.index ?? line.length;
+  const stripped = line.slice(0, index).replace(/[ \t]+$/, "");
+  return { line: stripped, annotation: { kind, lineCount } };
+}
+function collectCodeAnnotations(meta, code) {
+  const plan = parseCodeAnnotations(meta);
+  const strippedLines = [];
+  code.split("\n").forEach((rawLine, index) => {
+    const { line, annotation } = stripInlineCodeAnnotation(rawLine);
+    strippedLines.push(line);
+    if (!annotation) return;
+    const lineNumber = index + 1;
+    if (annotation.kind === "focus") {
+      for (let focused = lineNumber; focused < lineNumber + annotation.lineCount; focused += 1) {
+        plan.focus.push(focused);
+      }
+      return;
+    }
+    plan[annotation.kind].push(lineNumber);
+  });
+  const hasAnnotations2 = ANNOTATION_KEYS.some((key) => plan[key].length > 0);
+  return {
+    plan: hasAnnotations2 ? normalizePlan(plan) : createEmptyPlan(),
+    code: strippedLines.join("\n"),
+    hasAnnotations: hasAnnotations2
+  };
+}
+function normalizePlan(plan) {
+  return {
+    highlight: normalizeLines(plan.highlight),
+    added: normalizeLines(plan.added),
+    removed: normalizeLines(plan.removed),
+    focus: normalizeLines(plan.focus)
+  };
+}
+function hasAnnotations(plan) {
+  if (!plan) return false;
+  return ANNOTATION_KEYS.some((key) => plan[key].length > 0);
+}
+function serializeAnnotations(plan) {
+  return JSON.stringify(normalizePlan(plan));
+}
+function deserializeAnnotations(value) {
+  if (typeof value !== "string" || value === "") return null;
+  try {
+    return coercePlan(JSON.parse(value));
+  } catch {
+    return null;
+  }
+}
+function encodeAnnotationsMeta(plan) {
+  return `${ANNOTATIONS_META_PREFIX}${encodeURIComponent(
+    serializeAnnotations(plan)
+  )}`;
+}
+function appendAnnotationsMeta(meta, plan) {
+  const token = encodeAnnotationsMeta(plan);
+  const base = typeof meta === "string" ? meta.trim() : "";
+  return base === "" ? token : `${base} ${token}`;
+}
+function extractAnnotationsMeta(meta) {
+  if (typeof meta !== "string") return null;
+  const match = meta.match(/(?:^|\s)rb-annotations=([^\s]+)/);
+  if (!match) return null;
+  try {
+    return coercePlan(JSON.parse(decodeURIComponent(match[1])));
+  } catch {
+    return null;
+  }
+}
+function removeAnnotationsMeta(meta) {
+  if (typeof meta !== "string") return "";
+  return meta.replace(/(?:^|\s)rb-annotations=[^\s]+/g, " ").trim().replace(/\s+/g, " ");
+}
+function coercePlan(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const record = value;
+  return {
+    highlight: coerceLines(record.highlight),
+    added: coerceLines(record.added),
+    removed: coerceLines(record.removed),
+    focus: coerceLines(record.focus)
+  };
+}
+function coerceLines(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter(
+    (entry) => typeof entry === "number" && Number.isFinite(entry) && entry > 0
+  );
+}
+function addRanges(target, ranges) {
+  target.push(...ranges);
+}
+function normalizeLines(lines) {
+  return [...new Set(lines.filter((line) => line > 0))].sort(
+    (left, right) => left - right
+  );
+}
+function normalizeKind(kind) {
+  if (kind === "++") return "added";
+  if (kind === "--") return "removed";
+  if (kind === "focus") return "focus";
+  if (kind === "highlight") return "highlight";
+  return null;
+}
+
+// src/hast.ts
+function isElementNode(node) {
+  return node.type === "element";
+}
+function text(value) {
+  return { type: "text", value };
+}
+function element(tagName, properties = {}, children = []) {
+  return { type: "element", tagName, properties, children };
+}
+function visitElementTree(node, visitor, ancestors = []) {
+  if (isElementNode(node)) {
+    visitor(node, ancestors);
+  }
+  const nextAncestors = isElementNode(node) ? [...ancestors, node] : ancestors;
+  for (const child of getChildren(node)) {
+    visitElementTree(child, visitor, nextAncestors);
+  }
+}
+function getStringProperty(node, key) {
+  const value = getProperty(node, key);
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value.join(" ");
+  return null;
+}
+function getBooleanProperty(node, key) {
+  const value = getProperty(node, key);
+  return value === true || value === "true" || value === "";
+}
+function hasProperty(node, key) {
+  return getProperty(node, key) !== void 0;
+}
+function getClassNameList(node) {
+  const value = node.properties?.className;
+  if (Array.isArray(value)) {
+    return value.filter((entry) => typeof entry === "string");
+  }
+  if (typeof value === "string") {
+    return value.split(/\s+/).filter(Boolean);
+  }
+  return [];
+}
+function mergeClassName(current, next) {
+  const currentClass = Array.isArray(current) ? current.join(" ") : typeof current === "string" ? current : "";
+  if (next === "") return currentClass;
+  return currentClass ? `${currentClass} ${next}` : next;
+}
+function getDataMeta(node) {
+  if (node === null || node === void 0) return null;
+  const data = node.data;
+  if (data === null || typeof data !== "object") return null;
+  const meta = data.meta;
+  return typeof meta === "string" ? meta : null;
+}
+function getTextContent(node) {
+  if (node.type === "text" && "value" in node && typeof node.value === "string") {
+    return node.value;
+  }
+  return getChildren(node).map(getTextContent).join("");
+}
+function getProperty(node, key) {
+  const value = node.properties?.[key];
+  if (value !== void 0) return value;
+  const hyphenated = key.replace(
+    /[A-Z]/g,
+    (match) => `-${match.toLowerCase()}`
+  );
+  if (hyphenated !== key) return node.properties?.[hyphenated];
+  return void 0;
+}
+function getChildren(node) {
+  const children = node.children;
+  return Array.isArray(children) ? children : [];
+}
+
+// src/options.ts
+var DEFAULT_CODE_ANNOTATIONS_OPTIONS = {
+  className: "rb-code",
+  lineClassName: "rb-code__line",
+  highlightClassName: "rb-code__line--highlighted",
+  addedClassName: "rb-code__line--added",
+  removedClassName: "rb-code__line--removed",
+  focusClassName: "rb-code__line--focused"
+};
+function resolveCodeAnnotationsOptions(options = {}) {
+  const resolved = {
+    className: options.className ?? DEFAULT_CODE_ANNOTATIONS_OPTIONS.className,
+    lineClassName: options.lineClassName ?? DEFAULT_CODE_ANNOTATIONS_OPTIONS.lineClassName,
+    highlightClassName: options.highlightClassName ?? DEFAULT_CODE_ANNOTATIONS_OPTIONS.highlightClassName,
+    addedClassName: options.addedClassName ?? DEFAULT_CODE_ANNOTATIONS_OPTIONS.addedClassName,
+    removedClassName: options.removedClassName ?? DEFAULT_CODE_ANNOTATIONS_OPTIONS.removedClassName,
+    focusClassName: options.focusClassName ?? DEFAULT_CODE_ANNOTATIONS_OPTIONS.focusClassName
+  };
+  const language = options.language?.trim();
+  if (language) resolved.language = language;
+  return resolved;
+}
+
+// src/rehype.ts
+function rehypeCodeAnnotations(options = resolveCodeAnnotationsOptions()) {
+  return (tree) => {
+    visitElementTree(tree, (node, ancestors) => {
+      if (node.tagName !== "code") return;
+      const parent = ancestors[ancestors.length - 1];
+      if (parent?.tagName !== "pre") return;
+      const pre = parent;
+      const figure = findFigure(ancestors);
+      const plan = readPlan(node, pre, figure);
+      stripAnnotationsFromProperties(node);
+      if (plan === null || !hasAnnotations(plan)) return;
+      if (!languageMatches(node, options.language)) return;
+      applyPlan(node, pre, figure, plan, options);
+    });
+  };
+}
+function findFigure(ancestors) {
+  for (let index = ancestors.length - 1; index >= 0; index -= 1) {
+    if (getBooleanProperty(ancestors[index], "dataRehypePrettyCodeFigure")) {
+      return ancestors[index];
+    }
+  }
+  return null;
+}
+function readPlan(code, pre, figure) {
+  const fromAttribute = deserializeAnnotations(
+    getStringProperty(code, "dataRbCodeAnnotations") ?? getStringProperty(code, "data-rb-code-annotations")
+  );
+  if (fromAttribute) return fromAttribute;
+  const metas = [getDataMeta(figure), getDataMeta(pre), getDataMeta(code)];
+  for (const meta of metas) {
+    const plan = extractAnnotationsMeta(meta);
+    if (plan) return plan;
+  }
+  return null;
+}
+function stripAnnotationsFromProperties(code) {
+  if (!code.properties) return;
+  delete code.properties["data-rb-code-annotations"];
+  delete code.properties.dataRbCodeAnnotations;
+  for (const key of ["data-meta", "dataMeta"]) {
+    const value = code.properties[key];
+    if (typeof value !== "string") continue;
+    const stripped = removeAnnotationsMeta(value);
+    if (stripped !== "") code.properties[key] = stripped;
+    else delete code.properties[key];
+  }
+}
+function applyPlan(code, pre, figure, plan, options) {
+  const root = figure && getBooleanProperty(figure, "dataRehypePrettyCodeFigure") ? figure : pre;
+  root.properties = {
+    ...root.properties,
+    className: mergeClassName(root.properties?.className, options.className)
+  };
+  const lines = getLineElements(code);
+  if (lines.length > 0) {
+    lines.forEach((line, index) => {
+      applyLineClasses(line, index + 1, plan, options);
+    });
+    return;
+  }
+  const rawLines = getTextContent(code).replace(/\n$/, "").split("\n");
+  const children = [];
+  rawLines.forEach((lineText, index) => {
+    const classNames = [
+      options.lineClassName,
+      ...annotationClassNames(index + 1, plan, options)
+    ];
+    children.push(
+      element(
+        "span",
+        {
+          className: classNames.join(" "),
+          dataLine: String(index + 1)
+        },
+        [text(lineText)]
+      )
+    );
+    if (index < rawLines.length - 1) children.push(text("\n"));
+  });
+  code.children = children;
+}
+function applyLineClasses(line, lineNumber, plan, options) {
+  for (const name of annotationClassNames(lineNumber, plan, options)) {
+    line.properties = {
+      ...line.properties,
+      className: mergeClassName(line.properties?.className, name)
+    };
+  }
+}
+function annotationClassNames(lineNumber, plan, options) {
+  const names = [];
+  if (plan.highlight.includes(lineNumber)) {
+    names.push(options.highlightClassName);
+  }
+  if (plan.added.includes(lineNumber)) names.push(options.addedClassName);
+  if (plan.removed.includes(lineNumber)) names.push(options.removedClassName);
+  if (plan.focus.includes(lineNumber)) names.push(options.focusClassName);
+  return names;
+}
+function getLineElements(code) {
+  return (code.children ?? []).filter(isElementNode).filter((child) => {
+    if (child.tagName !== "span") return false;
+    if (hasProperty(child, "dataLine")) return true;
+    const classNames = getClassNameList(child);
+    return classNames.includes("line") || classNames.some((name) => name.endsWith("__line"));
+  });
+}
+function languageMatches(code, language) {
+  if (!language) return true;
+  return detectLanguage(code) === language;
+}
+function detectLanguage(code) {
+  const explicit = getStringProperty(code, "dataLanguage") ?? getStringProperty(code, "data-language");
+  if (explicit) return explicit;
+  for (const name of getClassNameList(code)) {
+    if (name.startsWith("language-")) return name.slice("language-".length);
+  }
+  return null;
+}
+
+// src/remark.ts
+function remarkCodeAnnotations(options = resolveCodeAnnotationsOptions()) {
+  return (tree) => {
+    visitMdast(tree, (node) => {
+      if (node.type !== "code" || typeof node.value !== "string") return;
+      if (options.language !== void 0 && node.lang !== options.language) {
+        return;
+      }
+      const meta = typeof node.meta === "string" ? node.meta : null;
+      const { plan, code, hasAnnotations: hasAnnotations2 } = collectCodeAnnotations(
+        meta,
+        node.value
+      );
+      if (!hasAnnotations2) return;
+      node.value = code;
+      const hProperties = {
+        ...node.data?.hProperties
+      };
+      hProperties["data-rb-code-annotations"] = serializeAnnotations(plan);
+      const existingMeta = hProperties["data-meta"] ?? hProperties.dataMeta;
+      hProperties["data-meta"] = typeof existingMeta === "string" && existingMeta !== "" ? appendAnnotationsMeta(existingMeta, plan) : encodeAnnotationsMeta(plan);
+      node.data = { ...node.data ?? {}, hProperties };
+    });
+  };
+}
+function visitMdast(node, visitor) {
+  visitor(node);
+  for (const child of node.children ?? []) visitMdast(child, visitor);
+}
+
+// index.ts
+function codeAnnotations(options = {}) {
+  const resolved = resolveCodeAnnotationsOptions(options);
+  return definePlugin({
+    name: "code-annotations",
+    order: 10,
+    options: resolved,
+    extendMarkdownPipeline: (pipeline) => {
+      pipeline.use(remarkCodeAnnotations, resolved);
+    },
+    extendHtmlPipeline: (pipeline) => {
+      pipeline.use(rehypeCodeAnnotations, resolved);
+    },
+    assets: [createStyleAsset("code-annotations")]
+  });
+}
+var codeAnnotationsPlugin = codeAnnotations;
+export {
+  ANNOTATIONS_META_PREFIX,
+  DEFAULT_CODE_ANNOTATIONS_OPTIONS,
+  codeAnnotations,
+  codeAnnotationsPlugin,
+  collectCodeAnnotations,
+  createEmptyPlan,
+  deserializeAnnotations,
+  encodeAnnotationsMeta,
+  extractAnnotationsMeta,
+  hasAnnotations,
+  parseCodeAnnotations,
+  parseLineRanges,
+  rehypeCodeAnnotations,
+  remarkCodeAnnotations,
+  resolveCodeAnnotationsOptions,
+  serializeAnnotations,
+  stripInlineCodeAnnotation
+};

package/dist/src/annotations.d.ts

@@ -0,0 +1,48 @@
+import type { CodeAnnotationKind, CodeAnnotationPlan } from "./types.js";
+/** Prefix used to smuggle a plan through the preserved fence meta channel. */
+export declare const ANNOTATIONS_META_PREFIX = "rb-annotations=";
+export declare function createEmptyPlan(): CodeAnnotationPlan;
+/**
+ * Parse the highlight/focus specifiers of a code fence meta string.
+ *
+ * Docusaurus-style `{1,3-5}` groups become `highlight` lines. An optional
+ * `focus:{1,2}` (or `focus={1,2}`) group becomes `focus` lines. Inline marker
+ * comments are not part of the meta string and are handled by
+ * {@link collectCodeAnnotations}.
+ */
+export declare function parseCodeAnnotations(meta: string | null | undefined): CodeAnnotationPlan;
+/**
+ * Parse a numeric range list such as `1,3-5` into sorted 1-based line numbers.
+ */
+export declare function parseLineRanges(spec: string): number[];
+export type InlineCodeAnnotation = {
+    kind: CodeAnnotationKind;
+    lineCount: number;
+};
+/**
+ * Remove a trailing `[!code ...]` marker comment from a line and report what
+ * it annotated. The comment prefix may be `//`, `#`, `--`, or an HTML comment.
+ */
+export declare function stripInlineCodeAnnotation(line: string): {
+    line: string;
+    annotation: InlineCodeAnnotation | null;
+};
+export type CollectedCodeAnnotations = {
+    plan: CodeAnnotationPlan;
+    code: string;
+    hasAnnotations: boolean;
+};
+/**
+ * Parse fence meta and inline markers from a code block, returning the
+ * annotation plan and the code text with marker comments removed.
+ */
+export declare function collectCodeAnnotations(meta: string | null | undefined, code: string): CollectedCodeAnnotations;
+export declare function normalizePlan(plan: CodeAnnotationPlan): CodeAnnotationPlan;
+export declare function hasAnnotations(plan: CodeAnnotationPlan | null): boolean;
+export declare function serializeAnnotations(plan: CodeAnnotationPlan): string;
+export declare function deserializeAnnotations(value: unknown): CodeAnnotationPlan | null;
+export declare function encodeAnnotationsMeta(plan: CodeAnnotationPlan): string;
+export declare function appendAnnotationsMeta(meta: string | null | undefined, plan: CodeAnnotationPlan): string;
+export declare function extractAnnotationsMeta(meta: string | null | undefined): CodeAnnotationPlan | null;
+/** Remove an embedded plan token, keeping any surrounding fence meta. */
+export declare function removeAnnotationsMeta(meta: string | null | undefined): string;

package/dist/src/hast.d.ts

@@ -0,0 +1,12 @@
+import type { ElementNode, HastNode, TextNode } from "./types.js";
+export declare function isElementNode(node: HastNode): node is ElementNode;
+export declare function text(value: string): TextNode;
+export declare function element(tagName: string, properties?: Record<string, unknown>, children?: HastNode[]): ElementNode;
+export declare function visitElementTree(node: HastNode, visitor: (node: ElementNode, ancestors: ElementNode[]) => void, ancestors?: ElementNode[]): void;
+export declare function getStringProperty(node: ElementNode, key: string): string | null;
+export declare function getBooleanProperty(node: ElementNode, key: string): boolean;
+export declare function hasProperty(node: ElementNode, key: string): boolean;
+export declare function getClassNameList(node: ElementNode): string[];
+export declare function mergeClassName(current: unknown, next: string): string;
+export declare function getDataMeta(node: ElementNode | null | undefined): string | null;
+export declare function getTextContent(node: HastNode): string;

package/dist/src/options.d.ts

@@ -0,0 +1,10 @@
+import type { CodeAnnotationsOptions, ResolvedCodeAnnotationsOptions } from "./types.js";
+export declare const DEFAULT_CODE_ANNOTATIONS_OPTIONS: {
+    readonly className: "rb-code";
+    readonly lineClassName: "rb-code__line";
+    readonly highlightClassName: "rb-code__line--highlighted";
+    readonly addedClassName: "rb-code__line--added";
+    readonly removedClassName: "rb-code__line--removed";
+    readonly focusClassName: "rb-code__line--focused";
+};
+export declare function resolveCodeAnnotationsOptions(options?: CodeAnnotationsOptions): ResolvedCodeAnnotationsOptions;

package/dist/src/rehype.d.ts

@@ -0,0 +1,8 @@
+import type { HastNode, ResolvedCodeAnnotationsOptions } from "./types.js";
+/**
+ * Materializes annotation plans recorded by {@link remarkCodeAnnotations}.
+ * Reuses existing per-line wrappers (for example the ones emitted by
+ * `rehype-pretty-code` through `@riebeckite/plugin-code-enhance`) and falls
+ * back to wrapping raw `<code>` text into `rb-code__line` spans.
+ */
+export declare function rehypeCodeAnnotations(options?: ResolvedCodeAnnotationsOptions): (tree: HastNode) => void;

package/dist/src/remark.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedCodeAnnotationsOptions } from "./types.js";
+/**
+ * Reads the fence meta and inline `[!code ...]` markers of every code block,
+ * strips the marker comments from the code text, and records the resulting
+ * plan for the rehype stage.
+ *
+ * The plan travels through two properties:
+ *
+ * - `data-rb-code-annotations` is the primary channel and is read directly for
+ *   plain `<pre><code>` blocks.
+ * - `data-meta` carries an encoded copy because
+ *   `rehype-pretty-code` (used by `@riebeckite/plugin-code-enhance`) replaces
+ *   the `<code>` element and drops its properties. code-enhance already reads
+ *   `data-meta`, so the copy survives on the generated `<figure>`.
+ */
+export declare function remarkCodeAnnotations(options?: ResolvedCodeAnnotationsOptions): (tree: unknown) => void;

package/dist/src/types.d.ts

@@ -0,0 +1,56 @@
+export type CodeAnnotationsOptions = {
+    /**
+     * Class applied to the code block root (`<pre>` or the
+     * `rehype-pretty-code` `<figure>`). Defaults to `"rb-code"`.
+     */
+    className?: string;
+    /**
+     * Class applied to each generated line wrapper. Defaults to
+     * `"rb-code__line"`. Existing line wrappers are not re-classed.
+     */
+    lineClassName?: string;
+    /** Class applied to highlighted lines. Defaults to `"rb-code__line--highlighted"`. */
+    highlightClassName?: string;
+    /** Class applied to `++` lines. Defaults to `"rb-code__line--added"`. */
+    addedClassName?: string;
+    /** Class applied to `--` lines. Defaults to `"rb-code__line--removed"`. */
+    removedClassName?: string;
+    /** Class applied to focused lines. Defaults to `"rb-code__line--focused"`. */
+    focusClassName?: string;
+    /**
+     * When set, annotations are only applied to code blocks whose detected
+     * language matches this value. Unset by default.
+     */
+    language?: string;
+};
+export type ResolvedCodeAnnotationsOptions = {
+    className: string;
+    lineClassName: string;
+    highlightClassName: string;
+    addedClassName: string;
+    removedClassName: string;
+    focusClassName: string;
+    language?: string;
+};
+export type CodeAnnotationPlan = {
+    highlight: number[];
+    added: number[];
+    removed: number[];
+    focus: number[];
+};
+export type CodeAnnotationKind = "highlight" | "added" | "removed" | "focus";
+export type ElementNode = {
+    type: string;
+    tagName?: string;
+    properties?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+    children?: HastNode[];
+};
+export type TextNode = {
+    type: "text";
+    value: string;
+};
+export type HastNode = ElementNode | TextNode | {
+    type: string;
+    [key: string]: unknown;
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@riebeckite/plugin-code-annotations",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./index.ts",
+      "default": "./dist/index.js"
+    },
+    "./style.css": "./style.css"
+  },
+  "dependencies": {
+    "@riebeckite/core": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README_ja.md",
+    "dist",
+    "style.css"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rerurate514/riebeckite.git",
+    "directory": "packages/plugins/code-annotations"
+  },
+  "homepage": "https://github.com/Rerurate514/riebeckite#readme",
+  "bugs": {
+    "url": "https://github.com/Rerurate514/riebeckite/issues"
+  },
+  "description": "Code block annotations, highlights, and diff markers for Riebeckite.",
+  "keywords": [
+    "riebeckite",
+    "plugin",
+    "code-blocks",
+    "syntax-highlighting"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "sideEffects": [
+    "./style.css"
+  ],
+  "scripts": {
+    "build": "node ../../../scripts/build_package.mjs"
+  }
+}

package/style.css

@@ -0,0 +1,36 @@
+.rb-code {
+  --rb-code-annotation-accent: var(--rb-color-accent, #686868);
+  position: relative;
+}
+
+.rb-code__line {
+  display: block;
+  min-width: 100%;
+}
+
+.rb-code__line--highlighted {
+  background: color-mix(
+    in srgb,
+    var(--rb-code-annotation-accent) 14%,
+    transparent
+  );
+}
+
+.rb-code__line--added {
+  background: color-mix(in srgb, #1f883d 14%, transparent);
+}
+
+.rb-code__line--removed {
+  background: color-mix(in srgb, #cf222e 14%, transparent);
+}
+
+.rb-code__line--focused {
+  background: color-mix(
+    in srgb,
+    var(--rb-code-annotation-accent) 10%,
+    transparent
+  );
+  outline: 1px solid
+    color-mix(in srgb, var(--rb-code-annotation-accent) 45%, transparent);
+  outline-offset: -1px;
+}