@vortexlabs/kirari-react 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @vortexlabs/kirari-react
+
+## 1.0.0
+
+### Major Changes
+
+- 14accd0: Release Kirari 1.0.0 with the core syntax highlighting APIs, Rehype and MDX integration, and React components and streaming hooks. Update the integrations to require Kirari 1.x.
+
+### Patch Changes
+
+- Updated dependencies [14accd0]
+- Updated dependencies [149d19f]
+  - @vortexlabs/kirari@1.0.0
+
+## 1.0.0
+
+### Major Changes
+
+- Release Kirari 1.0.0 with the core syntax highlighting APIs, Rehype and MDX integration, and React components and streaming hooks. Update the integrations to require Kirari 1.x.
+
+### Patch Changes
+
+- Updated dependencies
+  - @vortexlabs/kirari@1.0.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,60 @@
-# Temporary Holding Version
+# @vortexlabs/kirari-react
 
-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.
+Kirari highlighting as React elements. `<Code>` renders tokens as `<span>`
+elements, with no `dangerouslySetInnerHTML` and no hooks, so it works as a
+Server Component.
+
+## Install
+
+```sh
+npm install @vortexlabs/kirari @vortexlabs/kirari-react
+```
+
+Requires React 19. Kirari is a peer dependency.
+
+## Usage
+
+```tsx
+import { Code } from '@vortexlabs/kirari-react'
+import { typescript } from '@vortexlabs/kirari/languages/typescript'
+import '@vortexlabs/kirari/theme.css'
+
+<Code language={typescript} highlightLines={[1, [3, 4]]}>{source}</Code>
+```
+
+Output is `<pre class="kirari"><code>…</code></pre>` with the standard
+`kirari-*` classes, so every Kirari theme works. `language` defaults to
+JavaScript. Other props go to the `<pre>`.
+
+| Prop | Effect |
+| --- | --- |
+| `lines` | Wrap each line in `<span class="kirari-line" data-line="n">`. |
+| `highlightLines` | Lines or `[first, last]` ranges get `kirari-line-highlighted`. Implies `lines`. |
+| `lineClassName` | `(line) => class` for a line wrapper. `line` is `{ number, start, end }`. |
+| `decorations` | `{ start, end, className }` source ranges, as in [decorations](../../docs/decorations.md). |
+| `classes` | Extra classes per token type, e.g. `{ keyword: 'kw' }`. |
+| `tokenClassName` | `(token) => class` per token. |
+| `tokens` | Pre-scanned tokens instead of `children`. |
+
+Line numbers are CSS:
+
+```css
+.kirari-line::before { content: attr(data-line); display: inline-block; width: 3ch; margin-right: 2ch; opacity: 0.5; }
+```
+
+## Streaming
+
+```tsx
+'use client'
+import { useTokenStream } from '@vortexlabs/kirari-react/stream'
+
+const { tokens, write, end, reset } = useTokenStream(javascript)
+// write(chunk) as text arrives, then end()
+return <Code tokens={tokens} />
+```
+
+- Rescans only the unfinished tail. See [token streaming](../../docs/streaming.md).
+- Changing `language` starts a new, empty stream.
+- After `end()`, call `reset()` before writing again.
+- `/stream` is a client module; `<Code>` is not.
+- Managing tokens yourself? Use `createTokenStream` from `@vortexlabs/kirari/stream` with `applyPatch(tokens, patch)`.

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { Language, Token } from '@vortexlabs/kirari/core';
+import type { Decoration } from '@vortexlabs/kirari/decorations';
+export type LineRange = number | readonly [first: number, last: number];
+export interface Line {
+    readonly number: number;
+    readonly start: number;
+    readonly end: number;
+}
+export interface CodeProps extends Omit<ComponentPropsWithoutRef<'pre'>, 'children'> {
+    /** Source to highlight. Ignored when `tokens` is set. */
+    readonly children?: string;
+    /** Pre-scanned tokens, such as the output of `useTokenStream`. */
+    readonly tokens?: readonly Token[];
+    readonly language?: Language;
+    readonly classes?: Readonly<Record<string, string>>;
+    readonly tokenClassName?: (token: Token) => string | undefined;
+    readonly decorations?: readonly Decoration[];
+    /** Wrap each line in `<span class="kirari-line" data-line="n">`. */
+    readonly lines?: boolean;
+    readonly lineClassName?: (line: Line) => string | undefined;
+    /** One-based lines or inclusive ranges that receive `kirari-line-highlighted`. Implies `lines`. */
+    readonly highlightLines?: readonly LineRange[];
+}
+/** Highlighted code as React elements. Uses no hooks, so it also renders as a Server Component. */
+export declare const Code: ({ children, tokens, language, classes, tokenClassName, decorations, lines, lineClassName, highlightLines, className, ...props }: CodeProps) => ReactNode;
+export type { Decoration } from '@vortexlabs/kirari/decorations';
+export type { Language, Token } from '@vortexlabs/kirari/core';

package/dist/index.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { tokenize } from '@vortexlabs/kirari/core';
+import { javascript } from '@vortexlabs/kirari/languages/javascript';
+const join = (...names) => {
+    return names.filter(Boolean).join(' ');
+};
+const splitsSurrogate = (source, offset) => {
+    const before = source.charCodeAt(offset - 1);
+    const after = source.charCodeAt(offset);
+    return before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff;
+};
+const highlighted = (ranges) => {
+    const pairs = ranges.map(range => typeof range === 'number' ? [range, range] : range);
+    return line => pairs.some(([first, last]) => first <= line && line <= last);
+};
+const codeNodes = (tokens, options = {}) => {
+    let offset = 0;
+    for (const token of tokens) {
+        if (token.start !== offset || token.end !== offset + token.value.length) {
+            throw new RangeError('Kirari: tokens must cover contiguous source offsets starting at zero');
+        }
+        offset = token.end;
+    }
+    const source = tokens.map(token => token.value).join('');
+    const decorations = options.decorations ?? [];
+    const events = [];
+    for (const [index, decoration] of decorations.entries()) {
+        if (!Number.isInteger(decoration.start) || !Number.isInteger(decoration.end)
+            || decoration.start < 0 || decoration.start >= decoration.end || decoration.end > source.length) {
+            throw new RangeError('Kirari: decoration offsets must be integers with 0 <= start < end <= source length');
+        }
+        if (splitsSurrogate(source, decoration.start) || splitsSurrogate(source, decoration.end)) {
+            throw new RangeError('Kirari: decoration offsets must not split a UTF-16 surrogate pair');
+        }
+        events.push({ offset: decoration.start, index, entering: true }, { offset: decoration.end, index, entering: false });
+    }
+    events.sort((a, b) => a.offset - b.offset);
+    // Resolve callbacks once so tokens split by lines or decorations see them a single time.
+    const tokenClasses = tokens.map(token => join(options.classes && Object.hasOwn(options.classes, token.type) ? options.classes[token.type] : undefined, options.tokenClassName?.(token)));
+    const active = new Set();
+    let activeClasses = '';
+    let eventIndex = 0;
+    let tokenIndex = 0;
+    const rangeNodes = (start, end) => {
+        const nodes = [];
+        while (start < end) {
+            while (tokens[tokenIndex].end <= start)
+                tokenIndex++;
+            let changed = false;
+            while (eventIndex < events.length && events[eventIndex].offset <= start) {
+                const event = events[eventIndex++];
+                if (event.entering)
+                    active.add(event.index);
+                else
+                    active.delete(event.index);
+                changed = true;
+            }
+            if (changed)
+                activeClasses = [...active].sort((a, b) => a - b).map(index => decorations[index].className).join(' ');
+            const token = tokens[tokenIndex];
+            const stop = Math.min(end, token.end, events[eventIndex]?.offset ?? end);
+            const value = source.slice(start, stop);
+            const extra = join(tokenClasses[tokenIndex], activeClasses);
+            nodes.push(token.type === 'text' && !extra
+                ? value
+                : _jsx("span", { className: join(`kirari-${token.type}`, extra), children: value }, start));
+            start = stop;
+        }
+        return nodes;
+    };
+    const ranges = options.highlightLines ?? [];
+    if (!options.lines && ranges.length === 0)
+        return rangeNodes(0, source.length);
+    const isHighlighted = highlighted(ranges);
+    const nodes = [];
+    const newline = /\r\n|\r|\n/g;
+    let start = 0;
+    let number = 1;
+    do {
+        const match = newline.exec(source);
+        const end = match?.index ?? source.length;
+        const className = join('kirari-line', options.lineClassName?.({ number, start, end }), isHighlighted(number) ? 'kirari-line-highlighted' : undefined);
+        nodes.push(_jsx("span", { className: className, "data-line": number, children: rangeNodes(start, end) }, `line-${number}`));
+        if (!match)
+            break;
+        nodes.push(match[0]);
+        start = end + match[0].length;
+        number++;
+    } while (true);
+    return nodes;
+};
+/** Highlighted code as React elements. Uses no hooks, so it also renders as a Server Component. */
+export const Code = ({ children = '', tokens, language = javascript, classes, tokenClassName, decorations, lines, lineClassName, highlightLines, className, ...props }) => {
+    const nodes = codeNodes(tokens ?? tokenize(children, language), {
+        ...(classes && { classes }),
+        ...(tokenClassName && { tokenClassName }),
+        ...(decorations && { decorations }),
+        ...(lines && { lines }),
+        ...(lineClassName && { lineClassName }),
+        ...(highlightLines && { highlightLines }),
+    });
+    return _jsx("pre", { ...props, className: join('kirari', className), children: _jsx("code", { children: nodes }) });
+};

package/dist/stream.d.ts

@@ -0,0 +1,11 @@
+import type { Language, Token } from '@vortexlabs/kirari/core';
+import type { TokenPatch } from '@vortexlabs/kirari/stream';
+export interface StreamedTokens {
+    readonly tokens: readonly Token[];
+    write(chunk: string): void;
+    end(chunk?: string): void;
+    reset(): void;
+}
+export declare const applyPatch: (tokens: readonly Token[], patch: TokenPatch) => readonly Token[];
+/** Tokens for source that arrives in chunks. Pass the result's `tokens` to `<Code tokens>`. */
+export declare const useTokenStream: (language: Language) => StreamedTokens;

package/dist/stream.js

@@ -0,0 +1,24 @@
+'use client';
+import { useCallback, useMemo, useState } from 'react';
+import { createTokenStream } from '@vortexlabs/kirari/stream';
+export const applyPatch = (tokens, patch) => {
+    return [...tokens.filter(token => token.end <= patch.from), ...patch.tokens];
+};
+/** Tokens for source that arrives in chunks. Pass the result's `tokens` to `<Code tokens>`. */
+export const useTokenStream = (language) => {
+    const stream = useMemo(() => createTokenStream(language), [language]);
+    const [snapshot, setSnapshot] = useState({ stream, tokens: [] });
+    // A new language starts a new stream; tokens from the previous one no longer apply.
+    if (snapshot.stream !== stream)
+        setSnapshot({ stream, tokens: [] });
+    const apply = useCallback((patch) => {
+        setSnapshot(previous => previous.stream === stream ? { stream, tokens: applyPatch(previous.tokens, patch) } : previous);
+    }, [stream]);
+    const write = useCallback((chunk) => apply(stream.write(chunk)), [stream, apply]);
+    const end = useCallback((chunk) => apply(stream.end(chunk)), [stream, apply]);
+    const reset = useCallback(() => {
+        stream.reset();
+        setSnapshot({ stream, tokens: [] });
+    }, [stream]);
+    return { tokens: snapshot.stream === stream ? snapshot.tokens : [], write, end, reset };
+};

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@vortexlabs/kirari-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Kirari syntax highlighting as React elements.",
+  "keywords": [
+    "react",
+    "react-component",
+    "syntax-highlighting",
+    "server-components"
+  ],
+  "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/react"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./stream": {
+      "types": "./dist/stream.d.ts",
+      "import": "./dist/stream.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"
+  },
+  "peerDependencies": {
+    "@types/react": "^19",
+    "@vortexlabs/kirari": "^1.0.0",
+    "react": "^19"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.14.6",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vortexlabs/kirari": "1.0.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}