@eventuras/ratio-ui-shiki 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,394 @@
+Ratio UI Shiki — Shiki syntax highlighting for the Ratio UI design system
+Copyright (c) 2026 Losol AS.
+
+@eventuras/ratio-ui-shiki is licensed under the Mozilla Public License, Version 2.0 (MPL-2.0).
+The full license text is reproduced below and is also available at
+https://mozilla.org/MPL/2.0/.
+
+---
+
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+
+---
+
+1.1. "Contributor"
+means each individual or legal entity that creates, contributes to
+the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+means the combination of the Contributions of others (if any) used
+by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+means Source Code Form to which the initial Contributor has attached
+the notice in Exhibit A, the Executable Form of such Source Code
+Form, and Modifications of such Source Code Form, in each case
+including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+means a work that combines Covered Software with other material, in
+a separate file or files, that is not Covered Software.
+
+1.8. "License"
+means this document.
+
+1.9. "Licensable"
+means having the right to grant, to the maximum extent possible,
+whether at the time of the initial grant or subsequently, any and
+all of the rights conveyed by this License.
+
+1.10. "Modifications"
+means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+means any patent claim(s), including without limitation, method,
+process, and apparatus claims, in any patent Licensable by such
+Contributor that would be infringed, but for the grant of the
+License, by the making, using, selling, offering for sale, having
+made, import, or transfer of either its Contributions or its
+Contributor Version.
+
+1.12. "Secondary License"
+means either the GNU General Public License, Version 2.0, the GNU
+Lesser General Public License, Version 2.1, the GNU Affero General
+Public License, Version 3.0, or any later versions of those
+licenses.
+
+1.13. "Source Code Form"
+means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+means an individual or a legal entity exercising rights under this
+License. For legal entities, "You" includes any entity that
+controls, is controlled by, or is under common control with You. For
+purposes of this definition, "control" means (a) the power, direct
+or indirect, to cause the direction or management of such entity,
+whether by contract or otherwise, or (b) ownership of more than
+fifty percent (50%) of the outstanding shares or beneficial
+ownership of such entity.
+
+2. License Grants and Conditions
+
+---
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+Licensable by such Contributor to use, reproduce, make available,
+modify, display, perform, distribute, and otherwise exploit its
+Contributions, either on an unmodified basis, with Modifications, or
+as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+for sale, have made, import, and otherwise transfer either its
+Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+or
+
+(b) for infringements caused by: (i) Your and any other third party's
+modifications of Covered Software, or (ii) the combination of its
+Contributions with other software (except as part of its Contributor
+Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+
+---
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+Form, as described in Section 3.1, and You must inform recipients of
+the Executable Form how they can obtain a copy of such Source Code
+Form by reasonable means in a timely manner, at a charge no more
+than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+License, or sublicense it under different terms, provided that the
+license for the Executable Form does not attempt to limit or alter
+the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+
+---
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+
+---
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+---
+
+-                                                                      *
+- 6.  Disclaimer of Warranty *
+- ------------------------- *
+-                                                                      *
+- Covered Software is provided under this License on an "as is" *
+- basis, without warranty of any kind, either expressed, implied, or *
+- statutory, including, without limitation, warranties that the *
+- Covered Software is free of defects, merchantable, fit for a *
+- particular purpose or non-infringing. The entire risk as to the *
+- quality and performance of the Covered Software is with You. *
+- Should any Covered Software prove defective in any respect, You *
+- (not any Contributor) assume the cost of any necessary servicing, *
+- repair, or correction. This disclaimer of warranty constitutes an *
+- essential part of this License. No use of any Covered Software is *
+- authorized under this License except under this disclaimer. *
+-                                                                      *
+
+---
+
+---
+
+-                                                                      *
+- 7.  Limitation of Liability *
+- -------------------------- *
+-                                                                      *
+- Under no circumstances and under no legal theory, whether tort *
+- (including negligence), contract, or otherwise, shall any *
+- Contributor, or anyone who distributes Covered Software as *
+- permitted above, be liable to You for any direct, indirect, *
+- special, incidental, or consequential damages of any character *
+- including, without limitation, damages for lost profits, loss of *
+- goodwill, work stoppage, computer failure or malfunction, or any *
+- and all other commercial damages or losses, even if such party *
+- shall have been informed of the possibility of such damages. This *
+- limitation of liability shall not apply to liability for death or *
+- personal injury resulting from such party's negligence to the *
+- extent applicable law prohibits such limitation. Some *
+- jurisdictions do not allow the exclusion or limitation of *
+- incidental or consequential damages, so this exclusion and *
+- limitation may not apply to You. *
+-                                                                      *
+
+---
+
+8. Litigation
+
+---
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+
+---
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+
+---
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+This Source Code Form is "Incompatible With Secondary Licenses", as
+defined by the Mozilla Public License, v. 2.0.

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+# @eventuras/ratio-ui-shiki
 
-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.
+> ⚠️ **Alpha.** Experimental and unstable — the API may change or be removed
+> without notice, and it is published under the `alpha` npm dist-tag. Pin an
+> exact version if you depend on it.
+
+[Shiki](https://shiki.style) syntax highlighting for Ratio UI's
+[`CodeBlock`](../ratio-ui/src/core/CodeBlock). The core `CodeBlock` stays
+presentational and highlighter-agnostic; this companion package adds the Shiki
+layer so you don't wire it yourself.
+
+Built on `shiki/core` (fine-grained) with the WASM-free JavaScript regex engine,
+so consumers bundle only the curated grammars — not Shiki's full registry.
+
+## Installation
+
+```bash
+pnpm add @eventuras/ratio-ui @eventuras/ratio-ui-shiki shiki @shikijs/langs @shikijs/themes
+```
+
+`@eventuras/ratio-ui`, `shiki`, and Shiki's `@shikijs/langs` / `@shikijs/themes`
+are peer dependencies — you control their versions. The `@shikijs/*` packages
+ship with, and version-match, `shiki`.
+
+## Usage
+
+A drop-in for the core `CodeBlock` that highlights `code` client-side:
+
+```tsx
+import { CodeBlock } from '@eventuras/ratio-ui-shiki/CodeBlock';
+
+<CodeBlock code={source} language="tsx" />;
+```
+
+It loads a shared highlighter asynchronously and renders raw code until it is
+ready — no flash of missing content. Token colors **follow the app's light/dark
+mode** automatically (via `data-theme` / `data-color-scheme`, like the rest of
+ratio-ui).
+
+### Static / server-rendered highlighting
+
+For docs or RSC, highlight ahead of time and pass the result to the **core**
+`CodeBlock` — then no highlighter ships to the client:
+
+```tsx
+import { CodeBlock } from '@eventuras/ratio-ui/core/CodeBlock';
+import { createRatioHighlighter, shikiToDualLines, DUAL_THEME_CSS } from '@eventuras/ratio-ui-shiki';
+
+// Render DUAL_THEME_CSS once, high in your tree, so token colors follow the
+// app's light/dark mode (the client `<CodeBlock>` injects this for you):
+<style dangerouslySetInnerHTML={{ __html: DUAL_THEME_CSS }} />;
+
+const hl = await createRatioHighlighter();
+<CodeBlock
+  code={source}
+  language="tsx"
+  highlightedLines={shikiToDualLines(hl, source, 'tsx')}
+/>;
+```
+
+`shikiToLines` is the single-theme equivalent if you don't need light/dark (no
+`DUAL_THEME_CSS` needed — colors are inline). Because `highlightedLines` is an
+array of React nodes (not an HTML string), this path never uses
+`dangerouslySetInnerHTML` — it is injection-safe by construction.
+
+### Precomputed tokens: highlight at build time, render without Shiki
+
+When the page re-renders on the client (SPA, or React Router's `ssr: false` +
+prerender), `shikiToDualLines` isn't enough — whatever produces the lines must
+also run in the browser. Split it in two instead: tokenize in a **build
+script** with `codeToDualTokens`, ship the result as JSON, and render it with
+`tokensToLines` from the Shiki-free `tokens` entrypoint. The client then
+bundles ~1 kB — no grammars, no engine — and code is highlighted from the very
+first paint.
+
+```ts
+// build script (Node) — runs once per build
+import { createRatioHighlighter, codeToDualTokens } from '@eventuras/ratio-ui-shiki';
+
+const hl = await createRatioHighlighter();
+const tokens = codeToDualTokens(hl, source, 'tsx');
+await fs.writeFile('tokens.json', JSON.stringify(tokens));
+```
+
+```tsx
+// client — imports only the tiny tokens module, never Shiki
+import { CodeBlock } from '@eventuras/ratio-ui/core/CodeBlock';
+import { tokensToLines, DualThemeStyles } from '@eventuras/ratio-ui-shiki/tokens';
+import tokens from './tokens.json';
+
+<DualThemeStyles />
+<CodeBlock code={source} language="tsx" highlightedLines={tokensToLines(tokens)} />;
+```
+
+`shikiToDualLines(hl, code, lang)` is exactly
+`tokensToLines(codeToDualTokens(hl, code, lang))` — the two paths render
+byte-identical markup (unit-tested), so you can start client-side and move to
+precomputed tokens later without visual change.
+
+### Advanced: `useShikiHighlighter`
+
+The hook the `<CodeBlock>` wrapper is built on. It loads (and shares) the
+default highlighter for your own compositions — `null` while loading, then the
+ready highlighter:
+
+```tsx
+import { useMemo } from 'react';
+import { CodeBlock } from '@eventuras/ratio-ui/core/CodeBlock';
+import { shikiToDualLines } from '@eventuras/ratio-ui-shiki';
+import { useShikiHighlighter } from '@eventuras/ratio-ui-shiki/useShikiHighlighter';
+
+function Code({ source }: { source: string }) {
+  const hl = useShikiHighlighter();
+  const lines = useMemo(
+    () => (hl ? shikiToDualLines(hl, source, 'tsx') : undefined),
+    [hl, source],
+  );
+  return <CodeBlock code={source} language="tsx" highlightedLines={lines} />;
+}
+```
+
+Need other languages or themes? Create a highlighter with your own imports and
+pass it in (`langs` / `themes` **replace** the defaults, so include everything
+you need):
+
+```tsx
+const hl = await createRatioHighlighter({
+  langs: [import('@shikijs/langs/rust'), import('@shikijs/langs/tsx')],
+});
+// useShikiHighlighter(hl)  — or  <CodeBlock highlighter={hl} … />
+```
+
+## Notes
+
+- `createRatioHighlighter` preloads a curated language set (`DEFAULT_LANGS`: tsx,
+  ts, jsx, js, json, bash, css, html, markdown, yaml, xml, python, csharp) and
+  the `github-light` / `github-dark` pair. Pass `langs` / `themes` as Shiki
+  inputs (e.g. `import('@shikijs/langs/go')`) to change the set.
+- The client `<CodeBlock>` injects `DUAL_THEME_CSS` itself (React style
+  hoisting); include it manually only when you render dual-theme lines by hand.
+- Entrypoints are split for RSC: the root (`.`) is server-safe (highlighter
+  helpers + `DUAL_THEME_CSS` + types); the client component and hook live at
+  `@eventuras/ratio-ui-shiki/CodeBlock` and `.../useShikiHighlighter`; the
+  Shiki-free precomputed-token renderer lives at
+  `@eventuras/ratio-ui-shiki/tokens` (`tokensToLines`, `DualThemeStyles`,
+  `DUAL_THEME_CSS`, types — imports nothing from Shiki).

package/dist/CodeBlock/CodeBlock.d.ts

@@ -0,0 +1,40 @@
+import { default as React } from 'react';
+import { CodeBlockProps as CoreCodeBlockProps } from '@eventuras/ratio-ui/core/CodeBlock';
+import { HighlighterCore } from 'shiki/core';
+import { DualThemes } from '../highlighter';
+export interface CodeBlockProps extends Omit<CoreCodeBlockProps, 'highlightedLines'> {
+    /**
+     * Light + dark Shiki theme pair to render with. The colors follow the app's
+     * mode (`data-theme` / `data-color-scheme`), like the rest of ratio-ui.
+     *
+     * The built-in highlighter only loads `github-light` / `github-dark`; to
+     * render a different pair, also pass a `highlighter` that has those themes
+     * loaded — otherwise the block falls back to un-highlighted code.
+     * @default { light: 'github-light', dark: 'github-dark' }
+     */
+    themes?: DualThemes;
+    /**
+     * Reuse an existing highlighter — e.g. one shared singleton from
+     * `createRatioHighlighter` preloaded with your languages — instead of letting
+     * this component lazily create its own. Ensure it has `language` and both
+     * themes loaded; otherwise the block falls back to un-highlighted code.
+     */
+    highlighter?: HighlighterCore;
+}
+/**
+ * `CodeBlock`, wired to Shiki — a drop-in for `@eventuras/ratio-ui/core/CodeBlock`
+ * that highlights `code` for the given `language`. It loads a highlighter
+ * asynchronously (via `useShikiHighlighter`) and renders raw code until it is
+ * ready, so there is no flash of missing content (graceful degradation). Token
+ * colors follow the app's light/dark mode automatically.
+ *
+ * For static or server-rendered content, prefer the core `CodeBlock` with
+ * pre-computed `highlightedLines` (build them with `shikiToDualLines` +
+ * `DUAL_THEME_CSS`) so no highlighter ships to the client.
+ */
+export declare function CodeBlock({ code, language, themes, highlighter, ...rest }: Readonly<CodeBlockProps>): React.JSX.Element;
+export declare namespace CodeBlock {
+    var displayName: string;
+}
+export default CodeBlock;
+//# sourceMappingURL=CodeBlock.d.ts.map

package/dist/CodeBlock/CodeBlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeBlock.d.ts","sourceRoot":"","sources":["../../src/CodeBlock/CodeBlock.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAkB,MAAM,OAAO,CAAC;AACvC,OAAO,EAEL,KAAK,cAAc,IAAI,kBAAkB,EAC1C,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAInF,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;IAClF;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,QAAQ,EACR,MAAuB,EACvB,WAAW,EACX,GAAG,IAAI,EACR,EAAE,QAAQ,CAAC,cAAc,CAAC,qBA6B1B;yBAnCe,SAAS;;;AAsCzB,eAAe,SAAS,CAAC"}

package/dist/CodeBlock/CodeBlock.js

@@ -0,0 +1,55 @@
+/*! @eventuras/ratio-ui-shiki · Shiki syntax highlighting for ratio-ui · https://github.com/losol/ratio-ui · (c) 2026 Losol AS · MPL-2.0 */
+"use client";
+import { DualThemeStyles } from "../tokens/index.js";
+import { DEFAULT_THEMES, shikiToDualLines } from "../highlighter.js";
+import { useShikiHighlighter } from "../useShikiHighlighter/index.js";
+import { useMemo } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { CodeBlock } from "@eventuras/ratio-ui/core/CodeBlock";
+//#region src/CodeBlock/CodeBlock.tsx
+/**
+* `CodeBlock`, wired to Shiki — a drop-in for `@eventuras/ratio-ui/core/CodeBlock`
+* that highlights `code` for the given `language`. It loads a highlighter
+* asynchronously (via `useShikiHighlighter`) and renders raw code until it is
+* ready, so there is no flash of missing content (graceful degradation). Token
+* colors follow the app's light/dark mode automatically.
+*
+* For static or server-rendered content, prefer the core `CodeBlock` with
+* pre-computed `highlightedLines` (build them with `shikiToDualLines` +
+* `DUAL_THEME_CSS`) so no highlighter ships to the client.
+*/
+function CodeBlock$1({ code, language, themes = DEFAULT_THEMES, highlighter, ...rest }) {
+	const { light, dark } = themes;
+	const activeHighlighter = useShikiHighlighter(highlighter);
+	const highlightedLines = useMemo(() => {
+		const hl = activeHighlighter;
+		if (!hl || !language) return void 0;
+		const loadedThemes = hl.getLoadedThemes();
+		if (!hl.getLoadedLanguages().includes(language) || !loadedThemes.includes(light) || !loadedThemes.includes(dark)) return;
+		try {
+			return shikiToDualLines(hl, code, language, {
+				light,
+				dark
+			});
+		} catch {
+			return;
+		}
+	}, [
+		activeHighlighter,
+		code,
+		language,
+		light,
+		dark
+	]);
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(DualThemeStyles, {}), /* @__PURE__ */ jsx(CodeBlock, {
+		code,
+		language,
+		highlightedLines,
+		...rest
+	})] });
+}
+CodeBlock$1.displayName = "ShikiCodeBlock";
+//#endregion
+export { CodeBlock$1 as CodeBlock, CodeBlock$1 as default };
+
+//# sourceMappingURL=CodeBlock.js.map

package/dist/CodeBlock/CodeBlock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeBlock.js","names":[],"sources":["../../src/CodeBlock/CodeBlock.tsx"],"sourcesContent":["// ratio-ui · design system for knowledge sharing\n// SPDX-FileCopyrightText: 2026 Losol AS\n// SPDX-License-Identifier: MPL-2.0\n\n'use client';\n\nimport React, { useMemo } from 'react';\nimport {\n  CodeBlock as CoreCodeBlock,\n  type CodeBlockProps as CoreCodeBlockProps,\n} from '@eventuras/ratio-ui/core/CodeBlock';\nimport type { HighlighterCore } from 'shiki/core';\nimport { shikiToDualLines, DEFAULT_THEMES, type DualThemes } from '../highlighter';\nimport { DualThemeStyles } from '../tokens';\nimport { useShikiHighlighter } from '../useShikiHighlighter';\n\nexport interface CodeBlockProps extends Omit<CoreCodeBlockProps, 'highlightedLines'> {\n  /**\n   * Light + dark Shiki theme pair to render with. The colors follow the app's\n   * mode (`data-theme` / `data-color-scheme`), like the rest of ratio-ui.\n   *\n   * The built-in highlighter only loads `github-light` / `github-dark`; to\n   * render a different pair, also pass a `highlighter` that has those themes\n   * loaded — otherwise the block falls back to un-highlighted code.\n   * @default { light: 'github-light', dark: 'github-dark' }\n   */\n  themes?: DualThemes;\n  /**\n   * Reuse an existing highlighter — e.g. one shared singleton from\n   * `createRatioHighlighter` preloaded with your languages — instead of letting\n   * this component lazily create its own. Ensure it has `language` and both\n   * themes loaded; otherwise the block falls back to un-highlighted code.\n   */\n  highlighter?: HighlighterCore;\n}\n\n/**\n * `CodeBlock`, wired to Shiki — a drop-in for `@eventuras/ratio-ui/core/CodeBlock`\n * that highlights `code` for the given `language`. It loads a highlighter\n * asynchronously (via `useShikiHighlighter`) and renders raw code until it is\n * ready, so there is no flash of missing content (graceful degradation). Token\n * colors follow the app's light/dark mode automatically.\n *\n * For static or server-rendered content, prefer the core `CodeBlock` with\n * pre-computed `highlightedLines` (build them with `shikiToDualLines` +\n * `DUAL_THEME_CSS`) so no highlighter ships to the client.\n */\nexport function CodeBlock({\n  code,\n  language,\n  themes = DEFAULT_THEMES,\n  highlighter,\n  ...rest\n}: Readonly<CodeBlockProps>) {\n  const { light, dark } = themes;\n  const activeHighlighter = useShikiHighlighter(highlighter);\n\n  const highlightedLines = useMemo(() => {\n    const hl = activeHighlighter;\n    if (!hl || !language) return undefined;\n    const loadedThemes = hl.getLoadedThemes();\n    if (\n      !hl.getLoadedLanguages().includes(language) ||\n      !loadedThemes.includes(light) ||\n      !loadedThemes.includes(dark)\n    ) {\n      return undefined;\n    }\n    try {\n      return shikiToDualLines(hl, code, language, { light, dark });\n    } catch {\n      return undefined; // unknown grammar/theme → raw code fallback\n    }\n  }, [activeHighlighter, code, language, light, dark]);\n\n  return (\n    <>\n      {/* Injection-safe theme switch; React hoists + dedupes by href. */}\n      <DualThemeStyles />\n      <CoreCodeBlock code={code} language={language} highlightedLines={highlightedLines} {...rest} />\n    </>\n  );\n}\n\nCodeBlock.displayName = 'ShikiCodeBlock';\nexport default CodeBlock;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA+CA,SAAgB,YAAU,EACxB,MACA,UACA,SAAS,gBACT,aACA,GAAG,QACwB;CAC3B,MAAM,EAAE,OAAO,SAAS;CACxB,MAAM,oBAAoB,oBAAoB,WAAW;CAEzD,MAAM,mBAAmB,cAAc;EACrC,MAAM,KAAK;EACX,IAAI,CAAC,MAAM,CAAC,UAAU,OAAO,KAAA;EAC7B,MAAM,eAAe,GAAG,gBAAgB;EACxC,IACE,CAAC,GAAG,mBAAmB,CAAC,CAAC,SAAS,QAAQ,KAC1C,CAAC,aAAa,SAAS,KAAK,KAC5B,CAAC,aAAa,SAAS,IAAI,GAE3B;EAEF,IAAI;GACF,OAAO,iBAAiB,IAAI,MAAM,UAAU;IAAE;IAAO;GAAK,CAAC;EAC7D,QAAQ;GACN;EACF;CACF,GAAG;EAAC;EAAmB;EAAM;EAAU;EAAO;CAAI,CAAC;CAEnD,OACE,qBAAA,YAAA,EAAA,UAAA,CAEE,oBAAC,iBAAD,CAAkB,CAAA,GAClB,oBAAC,WAAD;EAAqB;EAAgB;EAA4B;EAAkB,GAAI;CAAO,CAAA,CAC9F,EAAA,CAAA;AAEN;AAEA,YAAU,cAAc"}

package/dist/CodeBlock/index.d.ts

@@ -0,0 +1,2 @@
+export { CodeBlock, type CodeBlockProps } from './CodeBlock';
+//# sourceMappingURL=index.d.ts.map

package/dist/CodeBlock/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/CodeBlock/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/CodeBlock/index.js

@@ -0,0 +1,3 @@
+/*! @eventuras/ratio-ui-shiki · Shiki syntax highlighting for ratio-ui · https://github.com/losol/ratio-ui · (c) 2026 Losol AS · MPL-2.0 */
+import { CodeBlock } from "./CodeBlock.js";
+export { CodeBlock };

package/dist/highlighter.d.ts

@@ -0,0 +1,68 @@
+import { default as React } from 'react';
+import { HighlighterCore } from 'shiki/core';
+import { BundledLanguage, BundledTheme, LanguageInput, ThemeInput } from 'shiki';
+import { DualTokenLine } from './tokens';
+export { SHIKI_TOKEN_CLASS, DUAL_THEME_CSS } from './tokens';
+/**
+ * Languages preloaded when you don't pass your own to {@link createRatioHighlighter}.
+ * Kept in sync with the fine-grained `@shikijs/langs/*` imports below.
+ */
+export declare const DEFAULT_LANGS: BundledLanguage[];
+/** A light + dark Shiki theme pair. */
+export interface DualThemes {
+    light: BundledTheme;
+    dark: BundledTheme;
+}
+/** Default light/dark theme pair — the code surface follows the app's mode. */
+export declare const DEFAULT_THEMES: DualThemes;
+export interface RatioHighlighterOptions {
+    /**
+     * Languages to preload, as Shiki language *inputs* (dynamic imports) — e.g.
+     * `import('@shikijs/langs/python')`, not the string names. Defaults to inputs
+     * for the {@link DEFAULT_LANGS} languages. Replaces the default set when set.
+     */
+    langs?: LanguageInput[];
+    /**
+     * Themes to preload, as Shiki theme inputs — e.g.
+     * `import('@shikijs/themes/nord')`. Defaults to the `github-light` /
+     * `github-dark` pair.
+     */
+    themes?: ThemeInput[];
+}
+/**
+ * Create a Shiki highlighter preconfigured for ratio-ui. Built on `shiki/core`
+ * (`createHighlighterCore`) with the WASM-free JavaScript regex engine and a
+ * curated, individually-imported language/theme set — so consumers bundle only
+ * these grammars, not Shiki's full bundled registry. The call is async and
+ * relatively heavy — create one and share it (the `<CodeBlock>` wrapper does).
+ */
+export declare function createRatioHighlighter(options?: RatioHighlighterOptions): Promise<HighlighterCore>;
+/**
+ * Turn `code` into one React node per line for a **single** theme — each a run
+ * of `<span>`s carrying Shiki's token colors. Injection-safe (real elements, no
+ * HTML string). `lang`/`theme` must already be loaded in `highlighter`.
+ */
+export declare function shikiToLines(highlighter: HighlighterCore, code: string, lang: BundledLanguage | string, theme?: BundledTheme | string): React.ReactNode[];
+/**
+ * Tokenize `code` for a **light + dark** theme pair into plain, serializable
+ * data ({@link DualTokenLine}) — each token carries both colors as
+ * `--shiki-light` / `--shiki-dark` custom properties. This is the build-time
+ * half of the precomputed pipeline: run it in a build script (Node), ship the
+ * result as JSON, and render it with `tokensToLines` from
+ * `@eventuras/ratio-ui-shiki/tokens` — the client then needs no highlighter,
+ * grammars, or engine at all. `lang` and both themes must already be loaded
+ * in `highlighter`.
+ */
+export declare function codeToDualTokens(highlighter: HighlighterCore, code: string, lang: BundledLanguage | string, themes?: DualThemes): DualTokenLine[];
+/**
+ * Turn `code` into one React node per line for a **light + dark** theme pair.
+ * Each token span carries both colors as `--shiki-light` / `--shiki-dark` custom
+ * properties and the {@link SHIKI_TOKEN_CLASS} class; pair it with
+ * {@link DUAL_THEME_CSS} so the color follows the app's mode. Injection-safe.
+ * `lang` and both themes must already be loaded in `highlighter`.
+ *
+ * Shorthand for `tokensToLines(codeToDualTokens(...))` — split the two halves
+ * yourself to highlight at build time and render without Shiki on the client.
+ */
+export declare function shikiToDualLines(highlighter: HighlighterCore, code: string, lang: BundledLanguage | string, themes?: DualThemes): React.ReactNode[];
+//# sourceMappingURL=highlighter.d.ts.map

package/dist/highlighter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlighter.d.ts","sourceRoot":"","sources":["../src/highlighter.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAmB,MAAM,OAAO,CAAC;AACxC,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACtF,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAI7D,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eAAe,EAc1C,CAAC;AAEF,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,+EAA+E;AAC/E,eAAO,MAAM,cAAc,EAAE,UAA2D,CAAC;AAEzF,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,eAAe,CAAC,CAuBtG;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,eAAe,EAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,eAAe,GAAG,MAAM,EAC9B,KAAK,GAAE,YAAY,GAAG,MAA4B,GACjD,KAAK,CAAC,SAAS,EAAE,CA0BnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,eAAe,EAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,eAAe,GAAG,MAAM,EAC9B,MAAM,GAAE,UAA2B,GAClC,aAAa,EAAE,CAiBjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,eAAe,EAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,eAAe,GAAG,MAAM,EAC9B,MAAM,GAAE,UAA2B,GAClC,KAAK,CAAC,SAAS,EAAE,CAEnB"}

package/dist/highlighter.js

@@ -0,0 +1,120 @@
+/*! @eventuras/ratio-ui-shiki · Shiki syntax highlighting for ratio-ui · https://github.com/losol/ratio-ui · (c) 2026 Losol AS · MPL-2.0 */
+import { tokensToLines } from "./tokens/index.js";
+import { Fragment } from "react";
+import { createHighlighterCore } from "shiki/core";
+import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
+import { jsx } from "react/jsx-runtime";
+//#region src/highlighter.tsx
+/**
+* Languages preloaded when you don't pass your own to {@link createRatioHighlighter}.
+* Kept in sync with the fine-grained `@shikijs/langs/*` imports below.
+*/
+var DEFAULT_LANGS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js",
+	"json",
+	"bash",
+	"css",
+	"html",
+	"markdown",
+	"yaml",
+	"xml",
+	"python",
+	"csharp"
+];
+/** Default light/dark theme pair — the code surface follows the app's mode. */
+var DEFAULT_THEMES = {
+	light: "github-light",
+	dark: "github-dark"
+};
+/**
+* Create a Shiki highlighter preconfigured for ratio-ui. Built on `shiki/core`
+* (`createHighlighterCore`) with the WASM-free JavaScript regex engine and a
+* curated, individually-imported language/theme set — so consumers bundle only
+* these grammars, not Shiki's full bundled registry. The call is async and
+* relatively heavy — create one and share it (the `<CodeBlock>` wrapper does).
+*/
+function createRatioHighlighter(options = {}) {
+	return createHighlighterCore({
+		engine: createJavaScriptRegexEngine(),
+		langs: options.langs ?? [
+			import("@shikijs/langs/tsx"),
+			import("@shikijs/langs/ts"),
+			import("@shikijs/langs/jsx"),
+			import("@shikijs/langs/js"),
+			import("@shikijs/langs/json"),
+			import("@shikijs/langs/bash"),
+			import("@shikijs/langs/css"),
+			import("@shikijs/langs/html"),
+			import("@shikijs/langs/markdown"),
+			import("@shikijs/langs/yaml"),
+			import("@shikijs/langs/xml"),
+			import("@shikijs/langs/python"),
+			import("@shikijs/langs/csharp")
+		],
+		themes: options.themes ?? [import("@shikijs/themes/github-light"), import("@shikijs/themes/github-dark")]
+	});
+}
+/**
+* Turn `code` into one React node per line for a **single** theme — each a run
+* of `<span>`s carrying Shiki's token colors. Injection-safe (real elements, no
+* HTML string). `lang`/`theme` must already be loaded in `highlighter`.
+*/
+function shikiToLines(highlighter, code, lang, theme = DEFAULT_THEMES.dark) {
+	const { tokens } = highlighter.codeToTokens(code, {
+		lang,
+		theme
+	});
+	return tokens.map((line, i) => /* @__PURE__ */ jsx(Fragment, { children: line.map((token, j) => {
+		const fontStyle = token.fontStyle ?? 0;
+		return /* @__PURE__ */ jsx("span", {
+			style: {
+				color: token.color,
+				fontStyle: fontStyle & 1 ? "italic" : void 0,
+				fontWeight: fontStyle & 2 ? "bold" : void 0,
+				textDecoration: fontStyle & 4 ? "underline" : void 0
+			},
+			children: token.content
+		}, j);
+	}) }, i));
+}
+/**
+* Tokenize `code` for a **light + dark** theme pair into plain, serializable
+* data ({@link DualTokenLine}) — each token carries both colors as
+* `--shiki-light` / `--shiki-dark` custom properties. This is the build-time
+* half of the precomputed pipeline: run it in a build script (Node), ship the
+* result as JSON, and render it with `tokensToLines` from
+* `@eventuras/ratio-ui-shiki/tokens` — the client then needs no highlighter,
+* grammars, or engine at all. `lang` and both themes must already be loaded
+* in `highlighter`.
+*/
+function codeToDualTokens(highlighter, code, lang, themes = DEFAULT_THEMES) {
+	const { tokens } = highlighter.codeToTokens(code, {
+		lang,
+		themes,
+		defaultColor: false
+	});
+	return tokens.map((line) => line.map((token) => ({
+		content: token.content,
+		...token.htmlStyle ? { htmlStyle: { ...token.htmlStyle } } : {}
+	})));
+}
+/**
+* Turn `code` into one React node per line for a **light + dark** theme pair.
+* Each token span carries both colors as `--shiki-light` / `--shiki-dark` custom
+* properties and the {@link SHIKI_TOKEN_CLASS} class; pair it with
+* {@link DUAL_THEME_CSS} so the color follows the app's mode. Injection-safe.
+* `lang` and both themes must already be loaded in `highlighter`.
+*
+* Shorthand for `tokensToLines(codeToDualTokens(...))` — split the two halves
+* yourself to highlight at build time and render without Shiki on the client.
+*/
+function shikiToDualLines(highlighter, code, lang, themes = DEFAULT_THEMES) {
+	return tokensToLines(codeToDualTokens(highlighter, code, lang, themes));
+}
+//#endregion
+export { DEFAULT_LANGS, DEFAULT_THEMES, codeToDualTokens, createRatioHighlighter, shikiToDualLines, shikiToLines };
+
+//# sourceMappingURL=highlighter.js.map

package/dist/highlighter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlighter.js","names":[],"sources":["../src/highlighter.tsx"],"sourcesContent":["// ratio-ui · design system for knowledge sharing\n// SPDX-FileCopyrightText: 2026 Losol AS\n// SPDX-License-Identifier: MPL-2.0\n\nimport React, { Fragment } from 'react';\nimport { createHighlighterCore, type HighlighterCore } from 'shiki/core';\nimport { createJavaScriptRegexEngine } from 'shiki/engine/javascript';\nimport type { BundledLanguage, BundledTheme, LanguageInput, ThemeInput } from 'shiki';\nimport { tokensToLines, type DualTokenLine } from './tokens';\n\n// Re-exported so existing imports keep working; they live in `./tokens` (the\n// Shiki-free module) so precomputed-token consumers don't pull this file in.\nexport { SHIKI_TOKEN_CLASS, DUAL_THEME_CSS } from './tokens';\n\n/**\n * Languages preloaded when you don't pass your own to {@link createRatioHighlighter}.\n * Kept in sync with the fine-grained `@shikijs/langs/*` imports below.\n */\nexport const DEFAULT_LANGS: BundledLanguage[] = [\n  'tsx',\n  'ts',\n  'jsx',\n  'js',\n  'json',\n  'bash',\n  'css',\n  'html',\n  'markdown',\n  'yaml',\n  'xml',\n  'python',\n  'csharp',\n];\n\n/** A light + dark Shiki theme pair. */\nexport interface DualThemes {\n  light: BundledTheme;\n  dark: BundledTheme;\n}\n\n/** Default light/dark theme pair — the code surface follows the app's mode. */\nexport const DEFAULT_THEMES: DualThemes = { light: 'github-light', dark: 'github-dark' };\n\nexport interface RatioHighlighterOptions {\n  /**\n   * Languages to preload, as Shiki language *inputs* (dynamic imports) — e.g.\n   * `import('@shikijs/langs/python')`, not the string names. Defaults to inputs\n   * for the {@link DEFAULT_LANGS} languages. Replaces the default set when set.\n   */\n  langs?: LanguageInput[];\n  /**\n   * Themes to preload, as Shiki theme inputs — e.g.\n   * `import('@shikijs/themes/nord')`. Defaults to the `github-light` /\n   * `github-dark` pair.\n   */\n  themes?: ThemeInput[];\n}\n\n/**\n * Create a Shiki highlighter preconfigured for ratio-ui. Built on `shiki/core`\n * (`createHighlighterCore`) with the WASM-free JavaScript regex engine and a\n * curated, individually-imported language/theme set — so consumers bundle only\n * these grammars, not Shiki's full bundled registry. The call is async and\n * relatively heavy — create one and share it (the `<CodeBlock>` wrapper does).\n */\nexport function createRatioHighlighter(options: RatioHighlighterOptions = {}): Promise<HighlighterCore> {\n  return createHighlighterCore({\n    engine: createJavaScriptRegexEngine(),\n    langs: options.langs ?? [\n      import('@shikijs/langs/tsx'),\n      import('@shikijs/langs/ts'),\n      import('@shikijs/langs/jsx'),\n      import('@shikijs/langs/js'),\n      import('@shikijs/langs/json'),\n      import('@shikijs/langs/bash'),\n      import('@shikijs/langs/css'),\n      import('@shikijs/langs/html'),\n      import('@shikijs/langs/markdown'),\n      import('@shikijs/langs/yaml'),\n      import('@shikijs/langs/xml'),\n      import('@shikijs/langs/python'),\n      import('@shikijs/langs/csharp'),\n    ],\n    themes: options.themes ?? [\n      import('@shikijs/themes/github-light'),\n      import('@shikijs/themes/github-dark'),\n    ],\n  });\n}\n\n/**\n * Turn `code` into one React node per line for a **single** theme — each a run\n * of `<span>`s carrying Shiki's token colors. Injection-safe (real elements, no\n * HTML string). `lang`/`theme` must already be loaded in `highlighter`.\n */\nexport function shikiToLines(\n  highlighter: HighlighterCore,\n  code: string,\n  lang: BundledLanguage | string,\n  theme: BundledTheme | string = DEFAULT_THEMES.dark,\n): React.ReactNode[] {\n  const { tokens } = highlighter.codeToTokens(code, {\n    lang: lang as BundledLanguage,\n    theme: theme as BundledTheme,\n  });\n\n  return tokens.map((line, i) => (\n    <Fragment key={i}>\n      {line.map((token, j) => {\n        const fontStyle = token.fontStyle ?? 0;\n        return (\n          <span\n            key={j}\n            style={{\n              color: token.color,\n              fontStyle: fontStyle & 1 ? 'italic' : undefined,\n              fontWeight: fontStyle & 2 ? 'bold' : undefined,\n              textDecoration: fontStyle & 4 ? 'underline' : undefined,\n            }}\n          >\n            {token.content}\n          </span>\n        );\n      })}\n    </Fragment>\n  ));\n}\n\n/**\n * Tokenize `code` for a **light + dark** theme pair into plain, serializable\n * data ({@link DualTokenLine}) — each token carries both colors as\n * `--shiki-light` / `--shiki-dark` custom properties. This is the build-time\n * half of the precomputed pipeline: run it in a build script (Node), ship the\n * result as JSON, and render it with `tokensToLines` from\n * `@eventuras/ratio-ui-shiki/tokens` — the client then needs no highlighter,\n * grammars, or engine at all. `lang` and both themes must already be loaded\n * in `highlighter`.\n */\nexport function codeToDualTokens(\n  highlighter: HighlighterCore,\n  code: string,\n  lang: BundledLanguage | string,\n  themes: DualThemes = DEFAULT_THEMES,\n): DualTokenLine[] {\n  const { tokens } = highlighter.codeToTokens(code, {\n    lang: lang as BundledLanguage,\n    themes: themes as unknown as Record<string, BundledTheme>,\n    defaultColor: false,\n  });\n\n  return tokens.map((line) =>\n    line.map((token) => ({\n      content: token.content,\n      // Copied into a fresh plain object so the result is JSON-clean no\n      // matter what Shiki hands back.\n      ...(token.htmlStyle\n        ? { htmlStyle: { ...(token.htmlStyle as Record<string, string>) } }\n        : {}),\n    })),\n  );\n}\n\n/**\n * Turn `code` into one React node per line for a **light + dark** theme pair.\n * Each token span carries both colors as `--shiki-light` / `--shiki-dark` custom\n * properties and the {@link SHIKI_TOKEN_CLASS} class; pair it with\n * {@link DUAL_THEME_CSS} so the color follows the app's mode. Injection-safe.\n * `lang` and both themes must already be loaded in `highlighter`.\n *\n * Shorthand for `tokensToLines(codeToDualTokens(...))` — split the two halves\n * yourself to highlight at build time and render without Shiki on the client.\n */\nexport function shikiToDualLines(\n  highlighter: HighlighterCore,\n  code: string,\n  lang: BundledLanguage | string,\n  themes: DualThemes = DEFAULT_THEMES,\n): React.ReactNode[] {\n  return tokensToLines(codeToDualTokens(highlighter, code, lang, themes));\n}\n"],"mappings":";;;;;;;;;;;AAkBA,IAAa,gBAAmC;CAC9C;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AASA,IAAa,iBAA6B;CAAE,OAAO;CAAgB,MAAM;AAAc;;;;;;;;AAwBvF,SAAgB,uBAAuB,UAAmC,CAAC,GAA6B;CACtG,OAAO,sBAAsB;EAC3B,QAAQ,4BAA4B;EACpC,OAAO,QAAQ,SAAS;GACtB,OAAO;GACP,OAAO;GACP,OAAO;GACP,OAAO;GACP,OAAO;GACP,OAAO;GACP,OAAO;GACP,OAAO;GACP,OAAO;GACP,OAAO;GACP,OAAO;GACP,OAAO;GACP,OAAO;EACT;EACA,QAAQ,QAAQ,UAAU,CACxB,OAAO,iCACP,OAAO,8BACT;CACF,CAAC;AACH;;;;;;AAOA,SAAgB,aACd,aACA,MACA,MACA,QAA+B,eAAe,MAC3B;CACnB,MAAM,EAAE,WAAW,YAAY,aAAa,MAAM;EAC1C;EACC;CACT,CAAC;CAED,OAAO,OAAO,KAAK,MAAM,MACvB,oBAAC,UAAD,EAAA,UACG,KAAK,KAAK,OAAO,MAAM;EACtB,MAAM,YAAY,MAAM,aAAa;EACrC,OACE,oBAAC,QAAD;GAEE,OAAO;IACL,OAAO,MAAM;IACb,WAAW,YAAY,IAAI,WAAW,KAAA;IACtC,YAAY,YAAY,IAAI,SAAS,KAAA;IACrC,gBAAgB,YAAY,IAAI,cAAc,KAAA;GAChD;GAEC,UAAA,MAAM;EACH,GATC,CASD;CAEV,CAAC,EACO,GAjBK,CAiBL,CACX;AACH;;;;;;;;;;;AAYA,SAAgB,iBACd,aACA,MACA,MACA,SAAqB,gBACJ;CACjB,MAAM,EAAE,WAAW,YAAY,aAAa,MAAM;EAC1C;EACE;EACR,cAAc;CAChB,CAAC;CAED,OAAO,OAAO,KAAK,SACjB,KAAK,KAAK,WAAW;EACnB,SAAS,MAAM;EAGf,GAAI,MAAM,YACN,EAAE,WAAW,EAAE,GAAI,MAAM,UAAqC,EAAE,IAChE,CAAC;CACP,EAAE,CACJ;AACF;;;;;;;;;;;AAYA,SAAgB,iBACd,aACA,MACA,MACA,SAAqB,gBACF;CACnB,OAAO,cAAc,iBAAiB,aAAa,MAAM,MAAM,MAAM,CAAC;AACxE"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createRatioHighlighter, shikiToLines, shikiToDualLines, codeToDualTokens, DEFAULT_LANGS, DEFAULT_THEMES, type RatioHighlighterOptions, type DualThemes, } from './highlighter';
+export { tokensToLines, DualThemeStyles, SHIKI_TOKEN_CLASS, DUAL_THEME_CSS, type DualToken, type DualTokenLine, } from './tokens';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,KAAK,uBAAuB,EAC5B,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AAIvB,OAAO,EACL,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,KAAK,SAAS,EACd,KAAK,aAAa,GACnB,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+/*! @eventuras/ratio-ui-shiki · Shiki syntax highlighting for ratio-ui · https://github.com/losol/ratio-ui · (c) 2026 Losol AS · MPL-2.0 */
+import { DUAL_THEME_CSS, DualThemeStyles, SHIKI_TOKEN_CLASS, tokensToLines } from "./tokens/index.js";
+import { DEFAULT_LANGS, DEFAULT_THEMES, codeToDualTokens, createRatioHighlighter, shikiToDualLines, shikiToLines } from "./highlighter.js";
+export { DEFAULT_LANGS, DEFAULT_THEMES, DUAL_THEME_CSS, DualThemeStyles, SHIKI_TOKEN_CLASS, codeToDualTokens, createRatioHighlighter, shikiToDualLines, shikiToLines, tokensToLines };

package/dist/tokens/index.d.ts

@@ -0,0 +1,46 @@
+import { default as React } from 'react';
+/** Class set on every dual-theme token span; {@link DUAL_THEME_CSS} switches its color. */
+export declare const SHIKI_TOKEN_CLASS = "ratio-shiki-token";
+/**
+ * CSS that flips token colors with the mode of the nearest scope. Shiki writes
+ * each token's light/dark colors into `--shiki-light` / `--shiki-dark`; a
+ * switch set on the scope — `:root` and its `data-theme` / `data-color-scheme`
+ * arms, `.surface-light` and `.surface-dark` — is inherited down to the token,
+ * which reads the dark color while the switch is on and falls back to light.
+ * The same scopes and the same inheritance as ratio-ui's own code-surface
+ * tokens, so a band inside a band resolves to the inner one. Rendered for you
+ * by {@link DualThemeStyles} and by the `<CodeBlock>` wrapper; include it
+ * yourself only if you render dual-theme lines by hand.
+ *
+ * The switch: `initial` is a custom property's guaranteed-invalid value, so
+ * `var()` of it voids `--shiki-color` and `color` takes its fallback. A lone
+ * space is a valid, empty value that leaves `--shiki-color` whole.
+ */
+export declare const DUAL_THEME_CSS = ":root,.surface-light{--shiki-dark-on:initial}\n:root[data-theme=\"dark\"],:root[data-color-scheme=\"dark\"],.surface-dark{--shiki-dark-on: }\n.ratio-shiki-token{--shiki-color:var(--shiki-dark-on) var(--shiki-dark);color:var(--shiki-color,var(--shiki-light))}";
+/**
+ * One Shiki token in serializable form: its text plus the inline style
+ * carrying the `--shiki-light` / `--shiki-dark` colors. Plain data — it
+ * survives `JSON.stringify`/`parse`, so tokens can be computed once at build
+ * time and shipped to the client instead of grammars.
+ */
+export interface DualToken {
+    content: string;
+    htmlStyle?: Record<string, string>;
+}
+/** One line of code as dual-theme tokens. */
+export type DualTokenLine = DualToken[];
+/**
+ * Renders {@link DUAL_THEME_CSS} as a hoisted `<style>` tag. React dedupes it
+ * by `href`, so rendering this next to Shiki `<CodeBlock>`s (which inject the
+ * same tag) adds nothing. Drop it once anywhere precomputed lines render.
+ */
+export declare function DualThemeStyles(): React.JSX.Element;
+/**
+ * Turn dual-theme tokens back into one React node per line — the shape core
+ * CodeBlock's `highlightedLines` takes. This is the runtime half of the
+ * precomputed pipeline: `codeToDualTokens` at build time, this at render.
+ * Injection-safe (real elements, no HTML string). Pair with
+ * {@link DualThemeStyles} so the colors follow the app's mode.
+ */
+export declare function tokensToLines(lines: DualTokenLine[]): React.ReactNode[];
+//# sourceMappingURL=index.d.ts.map

package/dist/tokens/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.tsx"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,KAAmB,MAAM,OAAO,CAAC;AAExC,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,uQAE6F,CAAC;AAEzH;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,6CAA6C;AAC7C,MAAM,MAAM,aAAa,GAAG,SAAS,EAAE,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,eAAe,sBAM9B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAcvE"}

package/dist/tokens/index.js

@@ -0,0 +1,60 @@
+/*! @eventuras/ratio-ui-shiki · Shiki syntax highlighting for ratio-ui · https://github.com/losol/ratio-ui · (c) 2026 Losol AS · MPL-2.0 */
+import { Fragment } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/tokens/index.tsx
+/**
+* The Shiki-free half of the precomputed-highlighting pipeline. Everything in
+* this module is plain data + tiny renderers with **no shiki import**, so a
+* client that renders precomputed tokens (built with `codeToDualTokens` at
+* build time) bundles about a kilobyte from here — no grammars, no engine.
+*/
+/** Class set on every dual-theme token span; {@link DUAL_THEME_CSS} switches its color. */
+var SHIKI_TOKEN_CLASS = "ratio-shiki-token";
+/**
+* CSS that flips token colors with the mode of the nearest scope. Shiki writes
+* each token's light/dark colors into `--shiki-light` / `--shiki-dark`; a
+* switch set on the scope — `:root` and its `data-theme` / `data-color-scheme`
+* arms, `.surface-light` and `.surface-dark` — is inherited down to the token,
+* which reads the dark color while the switch is on and falls back to light.
+* The same scopes and the same inheritance as ratio-ui's own code-surface
+* tokens, so a band inside a band resolves to the inner one. Rendered for you
+* by {@link DualThemeStyles} and by the `<CodeBlock>` wrapper; include it
+* yourself only if you render dual-theme lines by hand.
+*
+* The switch: `initial` is a custom property's guaranteed-invalid value, so
+* `var()` of it voids `--shiki-color` and `color` takes its fallback. A lone
+* space is a valid, empty value that leaves `--shiki-color` whole.
+*/
+var DUAL_THEME_CSS = `:root,.surface-light{--shiki-dark-on:initial}
+:root[data-theme="dark"],:root[data-color-scheme="dark"],.surface-dark{--shiki-dark-on: }
+.${SHIKI_TOKEN_CLASS}{--shiki-color:var(--shiki-dark-on) var(--shiki-dark);color:var(--shiki-color,var(--shiki-light))}`;
+/**
+* Renders {@link DUAL_THEME_CSS} as a hoisted `<style>` tag. React dedupes it
+* by `href`, so rendering this next to Shiki `<CodeBlock>`s (which inject the
+* same tag) adds nothing. Drop it once anywhere precomputed lines render.
+*/
+function DualThemeStyles() {
+	return /* @__PURE__ */ jsx("style", {
+		href: "ratio-ui-shiki-dual",
+		precedence: "medium",
+		children: DUAL_THEME_CSS
+	});
+}
+/**
+* Turn dual-theme tokens back into one React node per line — the shape core
+* CodeBlock's `highlightedLines` takes. This is the runtime half of the
+* precomputed pipeline: `codeToDualTokens` at build time, this at render.
+* Injection-safe (real elements, no HTML string). Pair with
+* {@link DualThemeStyles} so the colors follow the app's mode.
+*/
+function tokensToLines(lines) {
+	return lines.map((line, i) => /* @__PURE__ */ jsx(Fragment, { children: line.map((token, j) => /* @__PURE__ */ jsx("span", {
+		className: SHIKI_TOKEN_CLASS,
+		style: token.htmlStyle,
+		children: token.content
+	}, j)) }, i));
+}
+//#endregion
+export { DUAL_THEME_CSS, DualThemeStyles, SHIKI_TOKEN_CLASS, tokensToLines };
+
+//# sourceMappingURL=index.js.map

package/dist/tokens/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/tokens/index.tsx"],"sourcesContent":["// ratio-ui · design system for knowledge sharing\n// SPDX-FileCopyrightText: 2026 Losol AS\n// SPDX-License-Identifier: MPL-2.0\n\n/**\n * The Shiki-free half of the precomputed-highlighting pipeline. Everything in\n * this module is plain data + tiny renderers with **no shiki import**, so a\n * client that renders precomputed tokens (built with `codeToDualTokens` at\n * build time) bundles about a kilobyte from here — no grammars, no engine.\n */\n\nimport React, { Fragment } from 'react';\n\n/** Class set on every dual-theme token span; {@link DUAL_THEME_CSS} switches its color. */\nexport const SHIKI_TOKEN_CLASS = 'ratio-shiki-token';\n\n/**\n * CSS that flips token colors with the mode of the nearest scope. Shiki writes\n * each token's light/dark colors into `--shiki-light` / `--shiki-dark`; a\n * switch set on the scope — `:root` and its `data-theme` / `data-color-scheme`\n * arms, `.surface-light` and `.surface-dark` — is inherited down to the token,\n * which reads the dark color while the switch is on and falls back to light.\n * The same scopes and the same inheritance as ratio-ui's own code-surface\n * tokens, so a band inside a band resolves to the inner one. Rendered for you\n * by {@link DualThemeStyles} and by the `<CodeBlock>` wrapper; include it\n * yourself only if you render dual-theme lines by hand.\n *\n * The switch: `initial` is a custom property's guaranteed-invalid value, so\n * `var()` of it voids `--shiki-color` and `color` takes its fallback. A lone\n * space is a valid, empty value that leaves `--shiki-color` whole.\n */\nexport const DUAL_THEME_CSS = `:root,.surface-light{--shiki-dark-on:initial}\n:root[data-theme=\"dark\"],:root[data-color-scheme=\"dark\"],.surface-dark{--shiki-dark-on: }\n.${SHIKI_TOKEN_CLASS}{--shiki-color:var(--shiki-dark-on) var(--shiki-dark);color:var(--shiki-color,var(--shiki-light))}`;\n\n/**\n * One Shiki token in serializable form: its text plus the inline style\n * carrying the `--shiki-light` / `--shiki-dark` colors. Plain data — it\n * survives `JSON.stringify`/`parse`, so tokens can be computed once at build\n * time and shipped to the client instead of grammars.\n */\nexport interface DualToken {\n  content: string;\n  htmlStyle?: Record<string, string>;\n}\n\n/** One line of code as dual-theme tokens. */\nexport type DualTokenLine = DualToken[];\n\n/**\n * Renders {@link DUAL_THEME_CSS} as a hoisted `<style>` tag. React dedupes it\n * by `href`, so rendering this next to Shiki `<CodeBlock>`s (which inject the\n * same tag) adds nothing. Drop it once anywhere precomputed lines render.\n */\nexport function DualThemeStyles() {\n  return (\n    <style href=\"ratio-ui-shiki-dual\" precedence=\"medium\">\n      {DUAL_THEME_CSS}\n    </style>\n  );\n}\n\n/**\n * Turn dual-theme tokens back into one React node per line — the shape core\n * CodeBlock's `highlightedLines` takes. This is the runtime half of the\n * precomputed pipeline: `codeToDualTokens` at build time, this at render.\n * Injection-safe (real elements, no HTML string). Pair with\n * {@link DualThemeStyles} so the colors follow the app's mode.\n */\nexport function tokensToLines(lines: DualTokenLine[]): React.ReactNode[] {\n  return lines.map((line, i) => (\n    <Fragment key={i}>\n      {line.map((token, j) => (\n        <span\n          key={j}\n          className={SHIKI_TOKEN_CLASS}\n          style={token.htmlStyle as React.CSSProperties}\n        >\n          {token.content}\n        </span>\n      ))}\n    </Fragment>\n  ));\n}\n"],"mappings":";;;;;;;;;;;AAcA,IAAa,oBAAoB;;;;;;;;;;;;;;;;AAiBjC,IAAa,iBAAiB;;GAE3B,kBAAkB;;;;;;AAqBrB,SAAgB,kBAAkB;CAChC,OACE,oBAAC,SAAD;EAAO,MAAK;EAAsB,YAAW;EAC1C,UAAA;CACI,CAAA;AAEX;;;;;;;;AASA,SAAgB,cAAc,OAA2C;CACvE,OAAO,MAAM,KAAK,MAAM,MACtB,oBAAC,UAAD,EAAA,UACG,KAAK,KAAK,OAAO,MAChB,oBAAC,QAAD;EAEE,WAAW;EACX,OAAO,MAAM;EAEZ,UAAA,MAAM;CACH,GALC,CAKD,CACP,EACO,GAVK,CAUL,CACX;AACH"}

package/dist/useShikiHighlighter/index.d.ts

@@ -0,0 +1,14 @@
+import { HighlighterCore } from 'shiki/core';
+/**
+ * Load (and share) the ratio-ui Shiki highlighter — the curated default set
+ * from `createRatioHighlighter` (see its `DEFAULT_LANGS` + github light/dark).
+ * Returns `null` while it loads, then the ready highlighter. Pass your own
+ * `highlighter` — e.g. from `createRatioHighlighter` with extra language/theme
+ * imports — to skip loading.
+ *
+ * Pair the result with `shikiToDualLines` + `DUAL_THEME_CSS` to render code
+ * whose colors follow the app's light/dark mode. This is the primitive the
+ * `<CodeBlock>` wrapper is built on.
+ */
+export declare function useShikiHighlighter(highlighter?: HighlighterCore): HighlighterCore | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/useShikiHighlighter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/useShikiHighlighter/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAmBlD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,CAAC,EAAE,eAAe,GAAG,eAAe,GAAG,IAAI,CAyBzF"}

package/dist/useShikiHighlighter/index.js

@@ -0,0 +1,49 @@
+/*! @eventuras/ratio-ui-shiki · Shiki syntax highlighting for ratio-ui · https://github.com/losol/ratio-ui · (c) 2026 Losol AS · MPL-2.0 */
+"use client";
+import { createRatioHighlighter } from "../highlighter.js";
+import { useEffect, useState } from "react";
+//#region src/useShikiHighlighter/index.ts
+var defaultHighlighter;
+function getDefaultHighlighter() {
+	if (!defaultHighlighter) {
+		const created = createRatioHighlighter();
+		created.catch(() => {
+			if (defaultHighlighter === created) defaultHighlighter = void 0;
+		});
+		defaultHighlighter = created;
+	}
+	return defaultHighlighter;
+}
+/**
+* Load (and share) the ratio-ui Shiki highlighter — the curated default set
+* from `createRatioHighlighter` (see its `DEFAULT_LANGS` + github light/dark).
+* Returns `null` while it loads, then the ready highlighter. Pass your own
+* `highlighter` — e.g. from `createRatioHighlighter` with extra language/theme
+* imports — to skip loading.
+*
+* Pair the result with `shikiToDualLines` + `DUAL_THEME_CSS` to render code
+* whose colors follow the app's light/dark mode. This is the primitive the
+* `<CodeBlock>` wrapper is built on.
+*/
+function useShikiHighlighter(highlighter) {
+	const [active, setActive] = useState(highlighter ?? null);
+	useEffect(() => {
+		if (highlighter) {
+			setActive(highlighter);
+			return;
+		}
+		let alive = true;
+		setActive(null);
+		getDefaultHighlighter().then((h) => {
+			if (alive) setActive(h);
+		}).catch(() => {});
+		return () => {
+			alive = false;
+		};
+	}, [highlighter]);
+	return active;
+}
+//#endregion
+export { useShikiHighlighter };
+
+//# sourceMappingURL=index.js.map

package/dist/useShikiHighlighter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/useShikiHighlighter/index.ts"],"sourcesContent":["// ratio-ui · design system for knowledge sharing\n// SPDX-FileCopyrightText: 2026 Losol AS\n// SPDX-License-Identifier: MPL-2.0\n\n'use client';\n\nimport { useEffect, useState } from 'react';\nimport type { HighlighterCore } from 'shiki/core';\nimport { createRatioHighlighter } from '../highlighter';\n\n// The default highlighter (curated langs + github light/dark), created once and\n// shared across every component that doesn't pass its own.\nlet defaultHighlighter: Promise<HighlighterCore> | undefined;\n\nfunction getDefaultHighlighter(): Promise<HighlighterCore> {\n  if (!defaultHighlighter) {\n    const created = createRatioHighlighter();\n    // Don't cache a rejection forever — evict so a later mount can retry.\n    created.catch(() => {\n      if (defaultHighlighter === created) defaultHighlighter = undefined;\n    });\n    defaultHighlighter = created;\n  }\n  return defaultHighlighter;\n}\n\n/**\n * Load (and share) the ratio-ui Shiki highlighter — the curated default set\n * from `createRatioHighlighter` (see its `DEFAULT_LANGS` + github light/dark).\n * Returns `null` while it loads, then the ready highlighter. Pass your own\n * `highlighter` — e.g. from `createRatioHighlighter` with extra language/theme\n * imports — to skip loading.\n *\n * Pair the result with `shikiToDualLines` + `DUAL_THEME_CSS` to render code\n * whose colors follow the app's light/dark mode. This is the primitive the\n * `<CodeBlock>` wrapper is built on.\n */\nexport function useShikiHighlighter(highlighter?: HighlighterCore): HighlighterCore | null {\n  const [active, setActive] = useState<HighlighterCore | null>(highlighter ?? null);\n\n  useEffect(() => {\n    if (highlighter) {\n      setActive(highlighter);\n      return;\n    }\n    let alive = true;\n    // Drop any previously-provided highlighter while the default loads, so we\n    // never return a stale one (matches the \"null while loading\" contract).\n    setActive(null);\n    getDefaultHighlighter()\n      .then((h) => {\n        if (alive) setActive(h);\n      })\n      .catch(() => {\n        // Highlighter failed to init — stay on null (raw-code fallback).\n      });\n    return () => {\n      alive = false;\n    };\n  }, [highlighter]);\n\n  return active;\n}\n"],"mappings":";;;;;AAYA,IAAI;AAEJ,SAAS,wBAAkD;CACzD,IAAI,CAAC,oBAAoB;EACvB,MAAM,UAAU,uBAAuB;EAEvC,QAAQ,YAAY;GAClB,IAAI,uBAAuB,SAAS,qBAAqB,KAAA;EAC3D,CAAC;EACD,qBAAqB;CACvB;CACA,OAAO;AACT;;;;;;;;;;;;AAaA,SAAgB,oBAAoB,aAAuD;CACzF,MAAM,CAAC,QAAQ,aAAa,SAAiC,eAAe,IAAI;CAEhF,gBAAgB;EACd,IAAI,aAAa;GACf,UAAU,WAAW;GACrB;EACF;EACA,IAAI,QAAQ;EAGZ,UAAU,IAAI;EACd,sBAAsB,CAAC,CACpB,MAAM,MAAM;GACX,IAAI,OAAO,UAAU,CAAC;EACxB,CAAC,CAAC,CACD,YAAY,CAEb,CAAC;EACH,aAAa;GACX,QAAQ;EACV;CACF,GAAG,CAAC,WAAW,CAAC;CAEhB,OAAO;AACT"}

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@eventuras/ratio-ui-shiki",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Alpha — Shiki syntax highlighting for Ratio UI's CodeBlock",
+  "license": "MPL-2.0",
+  "homepage": "https://github.com/losol/ratio-ui/tree/main/packages/ratio-ui-shiki#readme",
+  "bugs": {
+    "url": "https://github.com/losol/ratio-ui/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/losol/ratio-ui.git",
+    "directory": "packages/ratio-ui-shiki"
+  },
+  "keywords": [
+    "ratio-ui",
+    "shiki",
+    "syntax-highlighting",
+    "codeblock",
+    "alpha"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./CodeBlock": {
+      "types": "./dist/CodeBlock/index.d.ts",
+      "import": "./dist/CodeBlock/index.js"
+    },
+    "./useShikiHighlighter": {
+      "types": "./dist/useShikiHighlighter/index.d.ts",
+      "import": "./dist/useShikiHighlighter/index.js"
+    },
+    "./tokens": {
+      "types": "./dist/tokens/index.d.ts",
+      "import": "./dist/tokens/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "devDependencies": {
+    "@eventuras/eslint-config": "^1.0.4",
+    "@eventuras/typescript-config": "^1.0.0",
+    "@eventuras/vite-config": "^0.3.1",
+    "@shikijs/langs": "^4.4.3",
+    "@shikijs/themes": "^4.4.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "shiki": "^4.4.3",
+    "typescript": "6.0.3",
+    "vite": "8.3.0",
+    "vitest": "4.1.11",
+    "@eventuras/ratio-ui": "2.31.1"
+  },
+  "peerDependencies": {
+    "@eventuras/ratio-ui": "^2.13.0",
+    "@shikijs/langs": "^4.4.3",
+    "@shikijs/themes": "^4.4.3",
+    "shiki": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsc && vite build",
+    "lint": "eslint .",
+    "test": "vitest run"
+  }
 }