@aparte/plugin-shiki 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aparté
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @aparte/plugin-shiki
+
+Syntax highlighting for [aparté](https://github.com/apartejs/aparte) via [shiki](https://shiki.style).
+Registers shiki as the highlight provider, backed by a **single lazily-created highlighter** — grammars
+and the theme load on demand and are cached, so you never re-initialise per code block.
+
+```bash
+npm install @aparte/plugin-shiki @aparte/core shiki
+```
+
+```ts
+import { setupShikiProvider } from '@aparte/plugin-shiki';
+
+await setupShikiProvider({ theme: 'github-dark' });
+```
+
+`@aparte/core` and `shiki` are **peer dependencies**. `setupShikiProvider` is async — `await` it once at
+startup before rendering highlighted messages.
+
+**Bundle**: nothing is eagerly bundled. Each language grammar is dynamically imported from shiki's bundle
+the first time it appears, so you pay only for the languages you actually render. An unknown language
+degrades to plain text instead of throwing.
+
+> ESM-only. Part of the aparté monorepo.

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { type BundledTheme } from 'shiki';
+export interface ShikiProviderOptions {
+    /**
+     * Theme to render with — a bundled theme name (e.g. `'github-dark'`) or a
+     * loaded custom theme name. Default `'github-dark'`.
+     */
+    theme?: BundledTheme | string;
+}
+/**
+ * Register [shiki](https://shiki.style) as aparté's syntax-highlight provider.
+ *
+ * Backed by a **single, lazily-created** `createHighlighter` instance: the
+ * highlighter is built once on first use with only the requested theme, and each
+ * language grammar is loaded on demand and cached. This is deliberately NOT the
+ * `codeToHtml` shorthand, which can re-initialise a highlighter per call — the
+ * cost we control here is why the plugin exists.
+ *
+ * Bundle note: nothing is eagerly bundled. Grammars/themes are dynamically
+ * imported from shiki's bundle the first time they are seen, so the highlighted
+ * languages a consumer actually renders are what they pay for.
+ *
+ * Framework-agnostic — vanilla, no framework imports. Call once at startup.
+ */
+export declare function setupShikiProvider(options?: ShikiProviderOptions): Promise<void>;
+//# 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":"AACA,OAAO,EAIH,KAAK,YAAY,EACpB,MAAM,OAAO,CAAC;AAEf,MAAM,WAAW,oBAAoB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;CACjC;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4C1F"}

package/dist/index.js

@@ -0,0 +1,39 @@
+import { AparteConfig } from "@aparte/core";
+import { createHighlighter } from "shiki";
+const PLAINTEXT = /* @__PURE__ */ new Set(["text", "plaintext", "txt", "ansi", ""]);
+async function setupShikiProvider(options = {}) {
+  const theme = options.theme ?? "github-dark";
+  let highlighter = null;
+  let creating = null;
+  const loadedLangs = /* @__PURE__ */ new Set();
+  const getHighlighter = () => {
+    if (highlighter) return Promise.resolve(highlighter);
+    if (!creating) {
+      creating = createHighlighter({ themes: [theme], langs: [] }).then((h) => {
+        highlighter = h;
+        return h;
+      }).catch((err) => {
+        creating = null;
+        throw err;
+      });
+    }
+    return creating;
+  };
+  AparteConfig.setHighlightProvider(async (code, lang) => {
+    const hl = await getHighlighter();
+    let language = (lang || "text").toLowerCase();
+    if (!PLAINTEXT.has(language) && !loadedLangs.has(language)) {
+      try {
+        await hl.loadLanguage(language);
+        loadedLangs.add(language);
+      } catch {
+        language = "text";
+      }
+    }
+    return hl.codeToHtml(code, { lang: language, theme });
+  });
+}
+export {
+  setupShikiProvider
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["import { AparteConfig } from '@aparte/core';\nimport {\n    createHighlighter,\n    type Highlighter,\n    type BundledLanguage,\n    type BundledTheme,\n} from 'shiki';\n\nexport interface ShikiProviderOptions {\n    /**\n     * Theme to render with — a bundled theme name (e.g. `'github-dark'`) or a\n     * loaded custom theme name. Default `'github-dark'`.\n     */\n    theme?: BundledTheme | string;\n}\n\nconst PLAINTEXT = new Set(['text', 'plaintext', 'txt', 'ansi', '']);\n\n/**\n * Register [shiki](https://shiki.style) as aparté's syntax-highlight provider.\n *\n * Backed by a **single, lazily-created** `createHighlighter` instance: the\n * highlighter is built once on first use with only the requested theme, and each\n * language grammar is loaded on demand and cached. This is deliberately NOT the\n * `codeToHtml` shorthand, which can re-initialise a highlighter per call — the\n * cost we control here is why the plugin exists.\n *\n * Bundle note: nothing is eagerly bundled. Grammars/themes are dynamically\n * imported from shiki's bundle the first time they are seen, so the highlighted\n * languages a consumer actually renders are what they pay for.\n *\n * Framework-agnostic — vanilla, no framework imports. Call once at startup.\n */\nexport async function setupShikiProvider(options: ShikiProviderOptions = {}): Promise<void> {\n    const theme = (options.theme ?? 'github-dark') as BundledTheme;\n\n    let highlighter: Highlighter | null = null;\n    let creating: Promise<Highlighter> | null = null;\n    const loadedLangs = new Set<string>();\n\n    const getHighlighter = (): Promise<Highlighter> => {\n        if (highlighter) return Promise.resolve(highlighter);\n        // De-dupe concurrent first calls so we only ever create one instance.\n        if (!creating) {\n            creating = createHighlighter({ themes: [theme], langs: [] })\n                .then((h) => {\n                    highlighter = h;\n                    return h;\n                })\n                .catch((err) => {\n                    // A transient failure (network/CSP on the dynamic theme import,\n                    // wasm engine hiccup) must NOT poison the singleton: clear the\n                    // cached promise so the next code block retries creation instead\n                    // of re-returning a permanently-rejected promise. Re-throw so this\n                    // block still degrades to plaintext via the provider's caller.\n                    creating = null;\n                    throw err;\n                });\n        }\n        return creating;\n    };\n\n    AparteConfig.setHighlightProvider(async (code, lang) => {\n        const hl = await getHighlighter();\n        let language = (lang || 'text').toLowerCase();\n\n        if (!PLAINTEXT.has(language) && !loadedLangs.has(language)) {\n            try {\n                await hl.loadLanguage(language as BundledLanguage);\n                loadedLangs.add(language);\n            } catch {\n                language = 'text'; // unknown grammar → render as plain text\n            }\n        }\n\n        return hl.codeToHtml(code, { lang: language, theme });\n    });\n}\n"],"names":[],"mappings":";;AAgBA,MAAM,gCAAgB,IAAI,CAAC,QAAQ,aAAa,OAAO,QAAQ,EAAE,CAAC;AAiBlE,eAAsB,mBAAmB,UAAgC,IAAmB;AACxF,QAAM,QAAS,QAAQ,SAAS;AAEhC,MAAI,cAAkC;AACtC,MAAI,WAAwC;AAC5C,QAAM,kCAAkB,IAAA;AAExB,QAAM,iBAAiB,MAA4B;AAC/C,QAAI,YAAa,QAAO,QAAQ,QAAQ,WAAW;AAEnD,QAAI,CAAC,UAAU;AACX,iBAAW,kBAAkB,EAAE,QAAQ,CAAC,KAAK,GAAG,OAAO,GAAC,CAAG,EACtD,KAAK,CAAC,MAAM;AACT,sBAAc;AACd,eAAO;AAAA,MACX,CAAC,EACA,MAAM,CAAC,QAAQ;AAMZ,mBAAW;AACX,cAAM;AAAA,MACV,CAAC;AAAA,IACT;AACA,WAAO;AAAA,EACX;AAEA,eAAa,qBAAqB,OAAO,MAAM,SAAS;AACpD,UAAM,KAAK,MAAM,eAAA;AACjB,QAAI,YAAY,QAAQ,QAAQ,YAAA;AAEhC,QAAI,CAAC,UAAU,IAAI,QAAQ,KAAK,CAAC,YAAY,IAAI,QAAQ,GAAG;AACxD,UAAI;AACA,cAAM,GAAG,aAAa,QAA2B;AACjD,oBAAY,IAAI,QAAQ;AAAA,MAC5B,QAAQ;AACJ,mBAAW;AAAA,MACf;AAAA,IACJ;AAEA,WAAO,GAAG,WAAW,MAAM,EAAE,MAAM,UAAU,OAAO;AAAA,EACxD,CAAC;AACL;"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@aparte/plugin-shiki",
+  "version": "0.2.0-alpha.0",
+  "description": "Syntax highlighting for aparté via shiki — register it as the highlight provider (single lazily-created highlighter).",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "@aparte-workspace/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "shiki": ">=1.0.0",
+    "@aparte/core": "0.2.0-alpha.0"
+  },
+  "devDependencies": {
+    "shiki": "^4.0.0",
+    "typescript": "^5.4.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "@aparte/core": "0.2.0-alpha.0"
+  },
+  "keywords": [
+    "aparte",
+    "plugin",
+    "highlight",
+    "syntax",
+    "shiki"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apartejs/aparte.git",
+    "directory": "packages/plugins/shiki"
+  },
+  "bugs": {
+    "url": "https://github.com/apartejs/aparte/issues"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc -b --emitDeclarationOnly --force",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}