@vortexlabs/kirari-rehype 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ugi (https://ugi.dev)
+
+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,174 @@
-# Temporary Holding Version
+# @vortexlabs/kirari-rehype
 
-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.
+Highlight code blocks in rendered Markdown and MDX with Kirari. This optional
+package converts Kirari tokens directly into structured HTML syntax tree nodes.
+It does not generate raw HTML or require a DOM.
+
+Run it while building your content to send highlighted HTML and CSS to the
+browser, with no client-side highlighter. The integration is separate from the
+core package and does not change its bundle.
+
+## Install
+
+```sh
+npm install @vortexlabs/kirari @vortexlabs/kirari-rehype
+```
+
+The plugin uses your application's Kirari through a peer dependency.
+Inside this workspace, use `workspace:*` for both packages instead.
+
+## Markdown to HTML
+
+Install `unified`, `remark-parse`, `remark-rehype`, and `rehype-stringify` in your
+application if it does not already have a Markdown pipeline.
+
+```ts
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import rehypeStringify from 'rehype-stringify'
+import rehypeKirari from '@vortexlabs/kirari-rehype'
+import { javascript } from '@vortexlabs/kirari/languages/javascript'
+import { typescript } from '@vortexlabs/kirari/languages/typescript'
+
+const processor = unified()
+  .use(remarkParse)
+  .use(remarkRehype)
+  .use(rehypeKirari, { languages: [javascript, typescript] })
+  .use(rehypeStringify)
+
+const source = '```js\nconst answer = 42\n```'
+const html = String(await processor.process(source))
+```
+
+Import the optional theme once from your application's stylesheet entry point:
+
+```ts
+import '@vortexlabs/kirari/theme.css'
+```
+
+The plugin adds `.kirari` to the enclosing `<pre>`, preserves existing properties
+and the code element's `language-*` class, and adds `.kirari-*` syntax spans.
+Customize colors with variables such as `--kirari-keyword` and `--kirari-variable`.
+
+## MDX
+
+Pass the same plugin to the MDX compiler's `rehypePlugins` option:
+
+```ts
+import { compile } from '@mdx-js/mdx'
+import rehypeKirari from '@vortexlabs/kirari-rehype'
+import { javascript } from '@vortexlabs/kirari/languages/javascript'
+
+const markdown = '```js\nconst answer = 42\n```'
+const compiled = await compile(markdown, {
+  rehypePlugins: [[rehypeKirari, { languages: [javascript] }]],
+})
+```
+
+Frameworks that configure MDX expose this option in different places. Keep the
+theme in the application entry point; it does not belong in compiler options.
+Custom MDX `pre` and `code` components should forward the generated properties
+and children.
+
+## Register only what you need
+
+No languages are registered by default. Import each definition and pass it in
+`languages`. Labels resolve through [Kirari's language registry](../../docs/language-integration.md),
+so `js` selects registered JavaScript and `ts` selects registered TypeScript.
+There is no language detection or automatic grammar loading. JSX and TSX need
+their own definitions.
+
+The plugin only highlights labelled, registered `<code>` elements directly
+inside `<pre>` whose children are all text nodes. It leaves unlabelled code,
+unknown languages, inline code, and code with existing element children
+untouched. A `no-highlight` or `nohighlight` class on either `pre` or `code` also
+skips the block. Ordinary Markdown serialization still escapes their text.
+
+`@vortexlabs/kirari/markdown` serves a different purpose: it colors Markdown source itself,
+including the fence markers. Use `@vortexlabs/kirari-rehype` when rendering a Markdown
+document into HTML or MDX.
+
+## Lines and fence metadata
+
+Add a standalone brace group to a fence's metadata to highlight lines:
+
+````md
+```js {2,4-6}
+const count = 1
+const doubled = count * 2
+
+console.log(count)
+console.log(doubled)
+console.log('done')
+```
+````
+
+Line numbers are one-based. Valid metadata enables `.kirari-line` wrappers with
+`data-line` attributes and adds `.kirari-line-highlighted` to selected lines.
+Malformed groups and groups inside quoted metadata values are ignored.
+Metadata is read from `code.data.meta`, as supplied by `remark-rehype` and MDX.
+
+Provide your own line highlight styling:
+
+```css
+.kirari-line-highlighted {
+  background: var(--kirari-line-background, #7452bd18);
+}
+```
+
+Use `lines: true` to wrap every highlighted block's lines even without metadata.
+The `lineClassName` callback can append your own classes:
+
+```ts
+import type { Options } from '@vortexlabs/kirari-rehype'
+
+const options = {
+  languages: [javascript],
+  lines: true,
+  lineClassName: ({ number }) => number === 1 ? 'opening-line' : undefined,
+} satisfies Options
+```
+
+Line endings remain outside the wrappers. Empty and trailing lines are
+preserved. Callback offsets are UTF-16 code units into the code block's source;
+`start` is inclusive and `end` is exclusive and excludes the line ending.
+Token class callbacks receive each original token once, even when a token spans
+multiple lines.
+
+## Options
+
+The default export is the plugin. `Options` is its exported TypeScript type.
+
+| Option | Default | Behavior |
+| --- | --- | --- |
+| `languages` | `[]` | Explicit readonly list of Kirari language definitions. |
+| `classes` | None | Token category to extra CSS class map, as in Kirari's `RenderOptions`. |
+| `className(token)` | None | Extra CSS classes for each original token. |
+| `lines` | `false` | Wrap every line of a highlighted block. Valid line metadata also enables wrappers. |
+| `lineClassName({ number, start, end })` | None | Extra classes for a line; called only when line wrappers are enabled. |
+
+Custom classes append to the standard Kirari classes. Plain `text` tokens remain
+text nodes unless they receive a custom class. Source strings become text node
+values, and classes become element properties; the downstream serializer or
+MDX compiler handles escaping.
+
+## Pipeline order
+
+Run the plugin after `remark-rehype`, when the document has become an HTML tree,
+and before `rehype-stringify`. In MDX, use `rehypePlugins`, not `remarkPlugins`.
+Configure one highlighter for a block; this plugin skips existing markup rather
+than removing another plugin's spans.
+
+If your pipeline sanitizes HTML, run `rehype-sanitize` before `rehypeKirari` and
+preserve the `language-*` classes needed for lookup. If sanitization runs after
+highlighting instead, its schema must allow Kirari's span classes, `.kirari` on
+`pre`, and `data-line` when lines are enabled.
+
+This plugin does not sanitize the surrounding document or change how your
+pipeline handles raw HTML or MDX expressions. Language definitions and callbacks
+remain trusted application code.
+
+## License
+
+[MIT](LICENSE) © 2026 [Ugi](https://ugi.dev)

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { Root } from 'hast';
+import type { Language, RenderOptions } from '@vortexlabs/kirari/core';
+export interface Options extends RenderOptions {
+    readonly languages?: readonly Language[];
+    readonly lines?: boolean;
+    readonly lineClassName?: (line: {
+        readonly number: number;
+        readonly start: number;
+        readonly end: number;
+    }) => string | undefined;
+}
+declare const rehypeKirari: (options?: Options) => (tree: Root) => undefined;
+export default rehypeKirari;

package/dist/index.js

@@ -0,0 +1,149 @@
+import { tokenize } from '@vortexlabs/kirari/core';
+import { createRegistry } from '@vortexlabs/kirari/registry';
+const classes = (value) => {
+    return (Array.isArray(value) ? value : [value])
+        .filter((item) => typeof item === 'string' || typeof item === 'number')
+        .flatMap(item => String(item).split(/[\t\n\f\r ]+/).filter(Boolean));
+};
+const lineRanges = (meta) => {
+    if (typeof meta !== 'string')
+        return [];
+    const ranges = [];
+    let quote = '';
+    let start = -1;
+    let depth = 0;
+    for (let index = 0; index < meta.length; index++) {
+        const char = meta[index];
+        if (char === '\\') {
+            index++;
+            start = -1;
+        }
+        else if (quote) {
+            if (char === quote)
+                quote = '';
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+            start = -1;
+        }
+        else if (char === '{') {
+            depth++;
+            start = depth === 1 && (index === 0 || /\s/.test(meta[index - 1])) ? index + 1 : -1;
+        }
+        else if (char === '}') {
+            depth = Math.max(0, depth - 1);
+            if (depth !== 0 || start < 0)
+                continue;
+            const body = meta.slice(start, index);
+            if ((index + 1 === meta.length || /\s/.test(meta[index + 1]))
+                && /^\s*[1-9]\d*(?:\s*-\s*[1-9]\d*)?(?:\s*,\s*[1-9]\d*(?:\s*-\s*[1-9]\d*)?)*\s*$/.test(body)) {
+                const parsed = body.split(',').map(part => {
+                    const [first, last = first] = part.split('-').map(Number);
+                    return [first, last];
+                });
+                if (parsed.every(([first, last]) => Number.isSafeInteger(first) && Number.isSafeInteger(last) && first <= last)) {
+                    for (const range of parsed)
+                        ranges.push(range);
+                }
+            }
+            start = -1;
+        }
+        else if (start >= 0 && !/[\d\s,-]/.test(char)) {
+            start = -1;
+        }
+    }
+    return ranges.sort((left, right) => left[0] - right[0]);
+};
+const tokenNodes = (source, tokens, options, ranges) => {
+    let offset = 0;
+    for (const token of tokens) {
+        if (token.start !== offset || token.end !== offset + token.value.length
+            || token.value !== source.slice(token.start, token.end)) {
+            throw new RangeError('Kirari: tokens must cover the original code contiguously');
+        }
+        offset = token.end;
+    }
+    if (offset !== source.length)
+        throw new RangeError('Kirari: tokens must cover the original code contiguously');
+    // Resolve callbacks once before any multiline token is split into line spans.
+    const tokenClasses = tokens.map(token => {
+        const mapped = options.classes && Object.hasOwn(options.classes, token.type) ? options.classes[token.type] : undefined;
+        const extra = [mapped, options.className?.(token)].filter(Boolean).join(' ');
+        return token.type === 'text' && !extra ? [] : classes(`kirari-${token.type}${extra ? ` ${extra}` : ''}`);
+    });
+    let tokenIndex = 0;
+    const rangeNodes = (start, end) => {
+        const nodes = [];
+        while (start < end) {
+            while (tokens[tokenIndex].end <= start)
+                tokenIndex++;
+            const token = tokens[tokenIndex];
+            const stop = Math.min(end, token.end);
+            const text = { type: 'text', value: source.slice(start, stop) };
+            const className = tokenClasses[tokenIndex];
+            nodes.push(className.length ? { type: 'element', tagName: 'span', properties: { className }, children: [text] } : text);
+            start = stop;
+        }
+        return nodes;
+    };
+    if (!options.lines && ranges.length === 0)
+        return rangeNodes(0, source.length);
+    const nodes = [];
+    const newline = /\r\n|\r|\n/g;
+    let start = 0;
+    let number = 1;
+    let rangeIndex = 0;
+    do {
+        const match = newline.exec(source);
+        const end = match?.index ?? source.length;
+        const className = ['kirari-line', ...classes(options.lineClassName?.({ number, start, end }))];
+        while (ranges[rangeIndex] && ranges[rangeIndex][1] < number)
+            rangeIndex++;
+        if (ranges[rangeIndex] && ranges[rangeIndex][0] <= number)
+            className.push('kirari-line-highlighted');
+        nodes.push({ type: 'element', tagName: 'span', properties: { className, dataLine: number }, children: rangeNodes(start, end) });
+        if (!match)
+            break;
+        nodes.push({ type: 'text', value: match[0] });
+        start = end + match[0].length;
+        number++;
+    } while (true);
+    return nodes;
+};
+const rehypeKirari = (options = {}) => {
+    const registry = createRegistry(options.languages ?? []);
+    return tree => {
+        const parents = [tree];
+        while (parents.length) {
+            const parent = parents.pop();
+            for (const child of parent.children) {
+                if (child.type === 'element' && child.tagName === 'pre') {
+                    const preClasses = classes(child.properties.className);
+                    if (!preClasses.some(name => name === 'no-highlight' || name === 'nohighlight')) {
+                        for (const code of child.children) {
+                            if (code.type !== 'element' || code.tagName !== 'code' || code.children.some(node => node.type !== 'text'))
+                                continue;
+                            const codeClasses = classes(code.properties.className);
+                            if (codeClasses.some(name => name === 'no-highlight' || name === 'nohighlight'))
+                                continue;
+                            const language = codeClasses.filter(name => name.startsWith('language-')).map(name => registry.resolve(name.slice(9))).find(Boolean);
+                            if (!language)
+                                continue;
+                            const source = code.children.map(node => node.type === 'text' ? node.value : '').join('');
+                            const meta = code.data && 'meta' in code.data ? code.data.meta : undefined;
+                            const children = tokenNodes(source, tokenize(source, language), options, lineRanges(meta));
+                            code.children = children;
+                            child.properties.className = [...new Set([...preClasses, 'kirari'])];
+                        }
+                    }
+                    continue;
+                }
+                // MDX JSX nodes can contain normal HAST children without being elements themselves.
+                if ('children' in child && Array.isArray(child.children))
+                    parents.push(child);
+            }
+        }
+        return undefined;
+    };
+};
+export default rehypeKirari;

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@vortexlabs/kirari-rehype",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Kirari syntax highlighting for Rehype and MDX.",
+  "keywords": [
+    "rehype",
+    "rehype-plugin",
+    "mdx",
+    "syntax-highlighting"
+  ],
+  "author": "Ugi (https://ugi.dev)",
+  "license": "MIT",
+  "homepage": "https://kirari.vortex.design",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vortexkit/kirari.git",
+    "directory": "packages/rehype"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test ./test",
+    "typecheck": "tsc --noEmit",
+    "check": "bun run typecheck && bun run test && bun run build && bun test ./checks",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@types/hast": "^3.0.5"
+  },
+  "peerDependencies": {
+    "@vortexlabs/kirari": "^0.1.0"
+  },
+  "devDependencies": {
+    "@mdx-js/mdx": "^3.1.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vortexlabs/kirari": "0.1.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "rehype-sanitize": "^6.0.0",
+    "rehype-stringify": "^10.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "unified": "^11.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}