@ugoku/astro 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @ugoku/astro
+
+## 0.1.1
+
+### Patch Changes
+
+- 1fd8164: Add a README to each published package.
+- Updated dependencies [1fd8164]
+  - @ugoku/core@0.1.1
+  - @ugoku/shiki@0.1.1

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,42 @@
-# Temporary Holding Version
+# @ugoku/astro
 
-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.
+Astro adapter for [ugoku](https://github.com/ugokujs/ugoku): runnable, editable code snippets for Shiki-highlighted fences, with no server and no DOM/iframe — console output only.
+
+A single integration auto-wires both the `@ugoku/shiki` transformer and the page script, for plain Astro's MPA navigation and `<ClientRouter />` transitions alike. (This is for plain Astro — Astro Starlight replaces Shiki with its own highlighter and needs a separate adapter.)
+
+## Setup
+
+```ts
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { ugoku } from '@ugoku/astro';
+
+export default defineConfig({
+  integrations: [ugoku()],
+});
+```
+
+That's it — no second manual step, no theme file to edit.
+
+## Usage
+
+Add `run` or `run edit` to a fence's info string:
+
+````md
+```js run
+console.log('hello');
+```
+
+```ts run edit
+function add(a: number, b: number): number {
+  return a + b;
+}
+console.log(add(2, 3));
+```
+````
+
+`run` is run-only; `run edit` additionally shows an editable overlay over the highlighted block, with edits persisted to `localStorage` per snippet.
+
+TypeScript blocks (`ts`) have their type annotations stripped in-browser (no type-checking) before execution.
+
+See the [main README](https://github.com/ugokujs/ugoku#readme) for the full picture.

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@ugoku/astro",
-  "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/astro"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts"
+  },
+  "dependencies": {
+    "@ugoku/core": "0.1.1",
+    "@ugoku/shiki": "0.1.1"
+  },
+  "devDependencies": {
+    "astro": "^5.0.0"
+  }
 }

package/src/client.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// no static top-level import of '@ugoku/core' — must be dynamic, see beforeEach
+
+interface FakeLink {
+  rel: string;
+  href: string;
+  dataset: Record<string, string>;
+}
+
+interface FakeDocument {
+  body: object;
+  head: {
+    querySelector: (selector: string) => FakeLink | null;
+    appendChild: (node: FakeLink) => void;
+  };
+  createElement: (tag: string) => FakeLink;
+  addEventListener: (type: string, listener: () => void) => void;
+}
+
+function stubDocument(): { fakeDocument: FakeDocument; listeners: Record<string, () => void> } {
+  const listeners: Record<string, () => void> = {};
+  let existingLink: FakeLink | null = null;
+  const fakeDocument: FakeDocument = {
+    body: {},
+    head: {
+      querySelector: (selector) => (selector === 'link[data-ugoku-styles]' ? existingLink : null),
+      appendChild: (node) => {
+        existingLink = node;
+      },
+    },
+    createElement: () => ({ rel: '', href: '', dataset: {} }),
+    addEventListener: (type, listener) => {
+      listeners[type] = listener;
+    },
+  };
+  (globalThis as { document?: FakeDocument }).document = fakeDocument;
+  return { fakeDocument, listeners };
+}
+
+describe('@ugoku/astro client', () => {
+  let mountSpy: ReturnType<typeof vi.spyOn>;
+  let unmountSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    const core = await import('@ugoku/core');
+    mountSpy = vi.spyOn(core, 'mount').mockImplementation(() => {});
+    unmountSpy = vi.spyOn(core, 'unmount').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    mountSpy.mockRestore();
+    unmountSpy.mockRestore();
+    delete (globalThis as { document?: unknown }).document;
+  });
+
+  it('mounts synchronously when the module is imported', async () => {
+    const { fakeDocument } = stubDocument();
+
+    await import('./client');
+
+    expect(mountSpy).toHaveBeenCalledTimes(1);
+    expect(mountSpy).toHaveBeenCalledWith(fakeDocument.body);
+  });
+
+  it('mounts again when astro:page-load fires', async () => {
+    const { fakeDocument, listeners } = stubDocument();
+    await import('./client');
+    mountSpy.mockClear();
+
+    listeners['astro:page-load']?.();
+
+    expect(mountSpy).toHaveBeenCalledTimes(1);
+    expect(mountSpy).toHaveBeenCalledWith(fakeDocument.body);
+  });
+
+  it('unmounts when astro:before-swap fires', async () => {
+    const { fakeDocument, listeners } = stubDocument();
+    await import('./client');
+
+    listeners['astro:before-swap']?.();
+
+    expect(unmountSpy).toHaveBeenCalledTimes(1);
+    expect(unmountSpy).toHaveBeenCalledWith(fakeDocument.body);
+  });
+});

package/src/client.ts

@@ -0,0 +1,23 @@
+import { mount, unmount } from '@ugoku/core';
+import stylesUrl from '@ugoku/core/styles.css?url';
+
+function ensureStyles() {
+  if (document.head.querySelector('link[data-ugoku-styles]')) return;
+  const link = document.createElement('link');
+  link.rel = 'stylesheet';
+  link.href = stylesUrl;
+  link.dataset.ugokuStyles = 'true';
+  document.head.appendChild(link);
+}
+
+ensureStyles();
+mount(document.body);
+
+document.addEventListener('astro:page-load', () => {
+  ensureStyles();
+  mount(document.body);
+});
+
+document.addEventListener('astro:before-swap', () => {
+  unmount(document.body);
+});

package/src/index.ts

@@ -0,0 +1 @@
+export { ugoku } from './integration.ts';

package/src/integration.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { AstroIntegration } from 'astro';
+import { ugoku } from './integration';
+
+type SetupHookArgs = Pick<
+  Parameters<NonNullable<AstroIntegration['hooks']['astro:config:setup']>>[0],
+  'updateConfig' | 'injectScript'
+>;
+
+function runSetupHook(integration: AstroIntegration, args: SetupHookArgs): void {
+  const setup = integration.hooks['astro:config:setup'];
+  if (!setup) throw new Error('astro:config:setup hook is missing');
+  setup(args as Parameters<NonNullable<AstroIntegration['hooks']['astro:config:setup']>>[0]);
+}
+
+describe('ugoku (Astro integration)', () => {
+  it('has the expected integration name', () => {
+    expect(ugoku().name).toBe('@ugoku/astro');
+  });
+
+  it('registers the ugoku Shiki transformer in markdown.shikiConfig.transformers', () => {
+    const updateConfig = vi.fn();
+    const injectScript = vi.fn();
+
+    runSetupHook(ugoku(), { updateConfig, injectScript });
+
+    expect(updateConfig).toHaveBeenCalledTimes(1);
+    const [config] = updateConfig.mock.calls[0];
+    const transformers = config.markdown.shikiConfig.transformers;
+    expect(transformers).toHaveLength(1);
+    expect(transformers[0].name).toBe('ugoku');
+  });
+
+  it('injects the client mount script at the page stage', () => {
+    const updateConfig = vi.fn();
+    const injectScript = vi.fn();
+
+    runSetupHook(ugoku(), { updateConfig, injectScript });
+
+    expect(injectScript).toHaveBeenCalledWith('page', expect.stringContaining('@ugoku/astro/client'));
+  });
+});

package/src/integration.ts

@@ -0,0 +1,20 @@
+import type { AstroIntegration } from 'astro';
+import { ugokuTransformer } from '@ugoku/shiki';
+
+export function ugoku(): AstroIntegration {
+  return {
+    name: '@ugoku/astro',
+    hooks: {
+      'astro:config:setup': ({ updateConfig, injectScript }) => {
+        updateConfig({
+          markdown: {
+            shikiConfig: {
+              transformers: [ugokuTransformer()],
+            },
+          },
+        });
+        injectScript('page', "import '@ugoku/astro/client';");
+      },
+    },
+  };
+}