@ugoku/shiki 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @ugoku/shiki
+
+## 0.1.1
+
+### Patch Changes
+
+- 1fd8164: Add a README to each published package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Skewis
+
+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,27 @@
-# Temporary Holding Version
+# @ugoku/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.
+The build-time [Shiki](https://shiki.style/) transformer for [ugoku](https://github.com/ugokujs/ugoku). Reads a code fence's meta string and, for `run`/`run edit` blocks, stamps the rendered `<pre>` with data attributes `@ugoku/core` reads at runtime (mode, language, theme(s), source hash). Blocks without `run` are left untouched.
+
+## Usage
+
+```ts
+import { ugokuTransformer } from '@ugoku/shiki';
+
+const transformer = ugokuTransformer();
+```
+
+Pass it wherever your Shiki setup accepts transformers — e.g. VitePress's `markdown.codeTransformers`, or Shiki's own `codeToHtml({ transformers: [...] })`.
+
+In markdown, add `run` (run-only) or `run edit` (editable) to the fence info string, alongside whatever else your pipeline already parses there (line numbers, filenames, etc.):
+
+````md
+```js run
+console.log('hello');
+```
+````
+
+## Who should use this directly
+
+If you're using the VitePress or Astro adapter, it already wires this in for you — see [`@ugoku/vitepress`](https://www.npmjs.com/package/@ugoku/vitepress) or [`@ugoku/astro`](https://www.npmjs.com/package/@ugoku/astro). Use this package directly only if you're building a custom Shiki integration.
+
+See the [main README](https://github.com/ugokujs/ugoku#readme) for the full picture.

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@ugoku/shiki",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ugokujs/ugoku.git",
+    "directory": "packages/shiki"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "peerDependencies": {
+    "shiki": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "shiki": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "shiki": "^4.5.0"
+  }
 }

package/src/hash.test.ts

@@ -0,0 +1,14 @@
+import { expect, test } from 'vitest';
+import { hashSource } from './hash';
+
+test('produces a 10-character lowercase hex string', () => {
+  expect(hashSource('console.log(1)')).toMatch(/^[0-9a-f]{10}$/);
+});
+
+test('is deterministic for the same source', () => {
+  expect(hashSource('const x = 1;')).toBe(hashSource('const x = 1;'));
+});
+
+test('changes when the source changes', () => {
+  expect(hashSource('const x = 1;')).not.toBe(hashSource('const x = 2;'));
+});

package/src/hash.ts

@@ -0,0 +1,7 @@
+import { createHash } from 'node:crypto';
+
+const HASH_LENGTH = 10;
+
+export function hashSource(source: string): string {
+  return createHash('sha256').update(source).digest('hex').slice(0, HASH_LENGTH);
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { ugokuTransformer } from './transformer.ts';

package/src/mode.test.ts

@@ -0,0 +1,32 @@
+import { expect, test } from 'vitest';
+import { resolveMode } from './mode';
+
+test('returns null when run is absent', () => {
+  expect(resolveMode(undefined)).toBeNull();
+  expect(resolveMode('')).toBeNull();
+  expect(resolveMode('{1,3}')).toBeNull();
+});
+
+test('returns run when run is present without edit', () => {
+  expect(resolveMode('run')).toBe('run');
+  expect(resolveMode('run {1,3}')).toBe('run');
+});
+
+test('returns run-edit when both run and edit are present', () => {
+  expect(resolveMode('run edit')).toBe('run-edit');
+  expect(resolveMode('edit run')).toBe('run-edit');
+});
+
+test('tokens coexist with other meta flags regardless of position', () => {
+  expect(resolveMode('{1,3} run :line-numbers edit [file.ts]')).toBe('run-edit');
+});
+
+test('downgrades to run when twoslash is also present', () => {
+  expect(resolveMode('run edit twoslash')).toBe('run');
+  expect(resolveMode('twoslash run edit')).toBe('run');
+});
+
+test('does not match run as a substring of another token', () => {
+  expect(resolveMode('run-something')).toBeNull();
+  expect(resolveMode('rerun')).toBeNull();
+});

package/src/mode.ts

@@ -0,0 +1,8 @@
+export type UgokuMode = 'run' | 'run-edit';
+
+export function resolveMode(rawMeta: string | undefined): UgokuMode | null {
+  const tokens = new Set((rawMeta ?? '').split(/\s+/).filter(Boolean));
+  if (!tokens.has('run')) return null;
+  if (tokens.has('edit') && !tokens.has('twoslash')) return 'run-edit';
+  return 'run';
+}

package/src/transformer.test.ts

@@ -0,0 +1,113 @@
+import { expect, test } from 'vitest';
+import { codeToHtml } from 'shiki';
+import type { ShikiTransformer } from 'shiki';
+import { ugokuTransformer } from './transformer';
+
+const theme = 'github-light';
+
+test('plain fence without run is left byte-identical', async () => {
+  const options = { lang: 'js' as const, theme, meta: { __raw: '{1,3}' } };
+  const withTransformer = await codeToHtml('const x = 1;', { ...options, transformers: [ugokuTransformer()] });
+  const withoutTransformer = await codeToHtml('const x = 1;', options);
+  expect(withTransformer).toBe(withoutTransformer);
+});
+
+test('run stamps data-ugoku-mode, lang, theme, and hash', async () => {
+  const html = await codeToHtml('const x = 1;', {
+    lang: 'js',
+    theme,
+    meta: { __raw: 'run' },
+    transformers: [ugokuTransformer()],
+  });
+  expect(html).toContain('data-ugoku-mode="run"');
+  expect(html).toContain('data-ugoku-lang="js"');
+  expect(html).toContain('data-ugoku-theme="github-light"');
+  expect(html).toMatch(/data-ugoku-hash="[0-9a-f]{10}"/);
+});
+
+test('run edit stamps run-edit', async () => {
+  const html = await codeToHtml('const x = 1;', {
+    lang: 'ts',
+    theme,
+    meta: { __raw: 'run edit' },
+    transformers: [ugokuTransformer()],
+  });
+  expect(html).toContain('data-ugoku-mode="run-edit"');
+});
+
+test('run and edit coexist with other meta tokens regardless of order', async () => {
+  const html = await codeToHtml('const x = 1;', {
+    lang: 'ts',
+    theme,
+    meta: { __raw: '{1,3} run :line-numbers edit [file.ts]' },
+    transformers: [ugokuTransformer()],
+  });
+  expect(html).toContain('data-ugoku-mode="run-edit"');
+});
+
+test('does not interfere with another transformer reading its own meta token', async () => {
+  const stub: ShikiTransformer = {
+    name: 'stub',
+    pre(hast) {
+      if (this.options.meta?.__raw?.includes(':line-numbers')) {
+        hast.properties['data-stub-line-numbers'] = 'true';
+      }
+    },
+  };
+  const html = await codeToHtml('const x = 1;', {
+    lang: 'ts',
+    theme,
+    meta: { __raw: 'run :line-numbers' },
+    transformers: [ugokuTransformer(), stub],
+  });
+  expect(html).toContain('data-ugoku-mode="run"');
+  expect(html).toContain('data-stub-line-numbers="true"');
+});
+
+test('run edit downgrades to run when twoslash is present', async () => {
+  const html = await codeToHtml('const x = 1;', {
+    lang: 'ts',
+    theme,
+    meta: { __raw: 'run edit twoslash' },
+    transformers: [ugokuTransformer()],
+  });
+  expect(html).toContain('data-ugoku-mode="run"');
+  expect(html).not.toContain('data-ugoku-mode="run-edit"');
+});
+
+test('dual-theme config stamps light and dark theme attributes', async () => {
+  const html = await codeToHtml('const x = 1;', {
+    lang: 'js',
+    themes: { light: 'github-light', dark: 'github-dark' },
+    meta: { __raw: 'run' },
+    transformers: [ugokuTransformer()],
+  });
+  expect(html).toContain('data-ugoku-theme-light="github-light"');
+  expect(html).toContain('data-ugoku-theme-dark="github-dark"');
+  expect(html).not.toContain('data-ugoku-theme=');
+});
+
+test('single-theme config stamps one theme attribute', async () => {
+  const html = await codeToHtml('const x = 1;', {
+    lang: 'js',
+    theme,
+    meta: { __raw: 'run' },
+    transformers: [ugokuTransformer()],
+  });
+  expect(html).toContain('data-ugoku-theme="github-light"');
+  expect(html).not.toContain('data-ugoku-theme-light=');
+});
+
+test('hash is deterministic for identical source and differs when source changes', async () => {
+  const makeHtml = (code: string) =>
+    codeToHtml(code, { lang: 'js', theme, meta: { __raw: 'run' }, transformers: [ugokuTransformer()] });
+
+  const first = await makeHtml('const x = 1;');
+  const same = await makeHtml('const x = 1;');
+  const different = await makeHtml('const x = 2;');
+
+  const extractHash = (html: string) => html.match(/data-ugoku-hash="([0-9a-f]{10})"/)?.[1];
+
+  expect(extractHash(first)).toBe(extractHash(same));
+  expect(extractHash(first)).not.toBe(extractHash(different));
+});

package/src/transformer.ts

@@ -0,0 +1,28 @@
+import type { ShikiTransformer } from 'shiki';
+import { resolveMode } from './mode.ts';
+import { hashSource } from './hash.ts';
+
+export function ugokuTransformer(): ShikiTransformer {
+  return {
+    name: 'ugoku',
+    pre(hast) {
+      const mode = resolveMode(this.options.meta?.__raw);
+      if (!mode) return;
+
+      hast.properties['data-ugoku-mode'] = mode;
+      hast.properties['data-ugoku-lang'] = this.options.lang;
+      hast.properties['data-ugoku-hash'] = hashSource(this.source);
+
+      // theme/themes can technically hold a full registration object, not just
+      // a name — but every real config (VitePress included) references themes
+      // by their string name.
+      if ('theme' in this.options && this.options.theme) {
+        hast.properties['data-ugoku-theme'] = this.options.theme as string;
+      } else if ('themes' in this.options && this.options.themes) {
+        const { light, dark } = this.options.themes as Record<string, string>;
+        if (light) hast.properties['data-ugoku-theme-light'] = light;
+        if (dark) hast.properties['data-ugoku-theme-dark'] = dark;
+      }
+    },
+  };
+}