@purview-dev/astroc4 1.0.0-prerelease.2 → 1.0.0-prerelease.3

package/README.md

@@ -139,7 +139,7 @@ with the integration options, so its own languages and the plugin's coexist.
 
 ### Translating
 
-Add any key from `src/translations.mjs` to the site's
+Add any key from `src/translations.ts` to the site's
 `src/content/i18n/<lang>.json`. Placeholders are `{name}` — single braces,
 because some are filled in by the browser, not by i18next.
 
@@ -161,7 +161,7 @@ bun run test:site      # pack the tarball and build a real Starlight site from i
 bun run check          # astro check over playground/ and src/
 bun run grammar:check  # fail if the committed grammar snapshot is stale
 bun run build && bun run preview
-bun scripts/smoke.mjs http://localhost:4321   # headless: hydration, icons, highlighting, i18n
+bun scripts/smoke.ts http://localhost:4321   # headless: hydration, icons, highlighting, i18n
 ```
 
 `Justfile` wraps each of those (`just verify` runs what the PR workflow runs).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purview-dev/astroc4",
-  "version": "1.0.0-prerelease.2",
+  "version": "1.0.0-prerelease.3",
   "description": "Interactive LikeC4 architecture diagrams for Astro and Starlight: <LikeC4View>, ```likec4 fences, and LikeC4 syntax highlighting derived from the live Langium grammar.",
   "license": "MIT",
   "author": {
@@ -32,29 +32,37 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/index.mjs",
-    "./expressive-code": "./src/expressive-code.mjs",
-    "./grammar/likec4.tmLanguage.json": "./src/grammar/likec4.tmLanguage.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./expressive-code": {
+      "types": "./dist/expressive-code.d.ts",
+      "import": "./dist/expressive-code.js"
+    },
+    "./grammar/likec4.tmLanguage.json": "./dist/likec4.tmLanguage.json",
     "./components/LikeC4View.astro": "./src/components/LikeC4View.astro",
     "./components/LikeC4Fence.astro": "./src/components/LikeC4Fence.astro"
   },
   "files": [
-    "src",
-    "!src/**/__tests__",
-    "!src/**/__fixtures__"
+    "dist",
+    "src/components",
+    "!src/components/__tests__",
+    "src/translations.ts"
   ],
   "scripts": {
-    "dev": "cd playground && astro dev",
-    "build": "cd playground && astro build",
+    "build:lib": "bun scripts/build.ts",
+    "dev": "bun run build:lib && cd playground && astro dev",
+    "build": "bun run build:lib && cd playground && astro build",
     "preview": "cd playground && astro preview",
-    "check": "cd playground && astro check",
+    "check": "bun run build:lib && cd playground && astro check && cd .. && bunx tsc -p tsconfig.scripts.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:network": "ASTROC4_NETWORK=1 vitest run src/grammar/__tests__/network.test.ts",
-    "test:site": "bun scripts/test-site.mjs",
-    "test:smoke": "node scripts/smoke.mjs",
-    "grammar:sync": "bun scripts/sync-grammar.mjs",
-    "grammar:check": "bun scripts/sync-grammar.mjs --check",
+    "test:site": "bun run build:lib && bun scripts/test-site.ts",
+    "test:smoke": "bun scripts/smoke.ts",
+    "grammar:sync": "bun scripts/sync-grammar.ts",
+    "grammar:check": "bun scripts/sync-grammar.ts --check",
     "likec4:validate": "likec4 validate playground/src/likec4"
   },
   "peerDependencies": {

package/src/components/labels.ts

@@ -4,7 +4,11 @@
 // the server and pass the islands plain strings, because `Astro.locals.t` does
 // not exist in the browser.
 
-import { translations } from '../translations.mjs';
+// Ships alongside this file: `files` publishes `src/components` *and*
+// `src/translations.ts`, so the components stay self-contained source. The
+// specifier keeps its `.js` extension because that is what the emitted
+// declarations carry and what the site's bundler maps back to this `.ts` file.
+import { translations } from '../translations.js';
 
 export type TranslationKey = keyof (typeof translations)['en'];
 export type Translate = (key: TranslationKey) => string;

package/src/expressive-code.d.mts

@@ -1,28 +0,0 @@
-// expressive-code.d.mts
-// path: src/expressive-code.d.mts
-// Types for src/expressive-code.mjs — see src/index.d.mts for why they exist.
-
-import type { LanguageRegistration } from 'shiki';
-
-/** Shiki registration for LikeC4, under `likec4` with a `c4` alias. */
-export declare const likec4Language: LanguageRegistration & { aliases: string[] };
-
-/**
- * Resolve the grammar from likec4/likec4 at the requested ref and return it as
- * a Shiki language registration.
- */
-export declare function loadLikeC4Language(options?: {
-	ref?: string;
-	repo?: string;
-	offline?: boolean;
-	onError?: 'fail' | 'warn' | 'silent';
-	cacheTtl?: number;
-	refresh?: boolean;
-	cacheDir?: string;
-	baseUrl?: string;
-	timeout?: number;
-	root?: string;
-}): Promise<LanguageRegistration & { aliases: string[] }>;
-
-export default likec4Language;
-

package/src/expressive-code.mjs

@@ -1,46 +0,0 @@
-// expressive-code.mjs
-// path: src/expressive-code.mjs
-// LikeC4 syntax highlighting for Expressive Code (Starlight's code blocks).
-// Shiki ships no LikeC4 grammar, so without this .c4 source renders as plain
-// text.
-//
-// The Starlight plugin injects this language into the site's Expressive Code
-// options for you (see src/index.mjs) resolved from the live Langium grammar.
-// The exports here cover the two cases the plugin cannot:
-//
-//   - a site that already has an `ec.config.mjs`, which can add the bundled
-//     grammar with one line:
-//
-//       import { likec4Language } from '@purview-dev/astroc4/expressive-code';
-//       export default defineEcConfig({ shiki: { langs: [likec4Language] } });
-//
-//   - anything else that needs the grammar programmatically, e.g. a Markdown
-//     pipeline of its own: `await loadLikeC4Language({ ref: 'v1.59.4' })`.
-//
-// `likec4Language` is the bundled snapshot, so it works without network
-// access; `loadLikeC4Language` fetches the ref you ask for.
-
-import grammar from './grammar/likec4.tmLanguage.json' with { type: 'json' };
-import { resolveLikeC4Grammar } from './grammar/source.mjs';
-import { LANGUAGE_ALIASES, LANGUAGE_NAME } from './grammar/textmate.mjs';
-
-/** @type {import('shiki').LanguageRegistration} */
-export const likec4Language = {
-	...grammar,
-	name: LANGUAGE_NAME,
-	aliases: [...LANGUAGE_ALIASES],
-};
-
-/**
- * Resolve the grammar from likec4/likec4 at the ref you ask for and return it
- * as a Shiki language registration.
- * @param {import('./grammar/source.mjs').GrammarSourceOptions} [options]
- * @returns {Promise<import('shiki').LanguageRegistration>}
- */
-export async function loadLikeC4Language(options) {
-	const { grammar: resolved } = await resolveLikeC4Grammar(options);
-
-	return { ...resolved, name: LANGUAGE_NAME, aliases: [...LANGUAGE_ALIASES] };
-}
-
-export default likec4Language;

package/src/fences.mjs

@@ -1,288 +0,0 @@
-// fences.mjs
-// path: src/fences.mjs
-// Turns a ```likec4 code fence into a rendered diagram instead of a code block.
-//
-// Two forms:
-//
-//   ```likec4 view="requestPath" title="Request path"
-//   ```
-//     -> renders a view from the site's LikeC4 project (any likec4.config.json).
-//
-//   ```likec4 title="Example"
-//   specification { element system }
-//   model { a = system 'A'  b = system 'B'  a -> b }
-//   views { view index { include * } }
-//   ```
-//     -> compiles and lays out this snippet at build time, then renders it.
-//
-// Layout needs LikeC4's WASM graph engine, so it has to happen during the
-// build; the browser only rehydrates the resulting JSON.
-//
-// This is a Sätteri mdast plugin, not a remark one. Astro 7 made Sätteri the
-// default Markdown processor, and `remarkPlugins` is a legacy option that is
-// silently ignored unless @astrojs/markdown-remark is installed. The plugin's
-// integration (src/index.mjs) registers it; sites do not add it themselves.
-
-import { createHash } from 'node:crypto';
-import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
-
-const require = createRequire(import.meta.url);
-
-// `likec4`'s Node API is deliberately NOT imported at module scope. It pulls in
-// Langium, chevrotain, an LSP and the WASM layout engine, and this module is
-// loaded as part of the site's astro.config.mjs — on a cold start that was
-// enough to make Astro report "Configuration file updated. Restarting...", and the restart
-// killed the content-layer transport, leaving every page a 500. Load it lazily
-// so the cost is paid only when a page actually contains an inline fence.
-let likec4ApiPromise;
-
-function loadLikeC4() {
-	// A plain `require('likec4')` rather than `import('likec4')`: Vite's SSR
-	// module runner intercepts dynamic `import()` from any module it loaded
-	// (this one included) to route it through the runner's own module graph —
-	// and on Windows that runner can already be mid-teardown by the time a
-	// page's ```likec4 fence triggers this, crashing the whole `astro build`
-	// (see `preloadLikeC4` below). `require()` goes through Node's own
-	// resolver instead, which Node 22+ supports for ESM-only packages like
-	// this one, sidestepping the runner entirely.
-	likec4ApiPromise ??= Promise.resolve(require('likec4').LikeC4);
-
-	return likec4ApiPromise;
-}
-
-/**
- * Kick off (and await) the same lazy load `loadLikeC4()` uses, so a later
- * call inside Satteri's processing reuses the already-resolved promise
- * instead of issuing a fresh `import('likec4')`.
- *
- * `astro build` on Windows crashes mid-build ("Vite module runner has been
- * closed", followed by a native libuv assertion that kills the process) if
- * that first `import('likec4')` happens while Vite is tearing down the SSR
- * module runner used for the content layer — which is exactly when the first
- * page containing a ```likec4 fence is rendered. Finishing the import before
- * that point removes the race. src/index.mjs calls this from
- * `astro:config:setup` for builds only — the module-scope comment above
- * `loadLikeC4` explains why eager-loading it in dev is unsafe.
- */
-export function preloadLikeC4() {
-	return loadLikeC4();
-}
-
-const FENCE_LANG = 'likec4';
-
-/** Component the fence is rewritten into, per form. */
-const INLINE_COMPONENT = '__LikeC4Fence';
-const PROJECT_COMPONENT = '__LikeC4View';
-
-// Package specifiers, not relative paths: the import is written into the page
-// being compiled, so it has to resolve from the site, not from this file.
-/** The published package name; see the comment on `PACKAGE_NAME` in index.mjs. */
-const PACKAGE_NAME = '@purview-dev/astroc4';
-
-const IMPORTS = {
-	[INLINE_COMPONENT]: `${PACKAGE_NAME}/components/LikeC4Fence.astro`,
-	[PROJECT_COMPONENT]: `${PACKAGE_NAME}/components/LikeC4View.astro`,
-};
-
-/**
- * Compiling a snippet costs ~250ms (a Langium workspace per call) and the same
- * page is re-rendered on every dev edit, so key on the source: a build pays
- * that once per distinct snippet, not once per render.
- */
-const layoutCache = new Map();
-
-/** Parse `key="value"` / `key=value` pairs from the fence's meta string. */
-export function parseFenceMeta(meta) {
-	const options = {};
-
-	if (!meta) return options;
-
-	const pattern = /(\w+)=(?:"([^"]*)"|'([^']*)'|(\S+))/g;
-	let match;
-
-	while ((match = pattern.exec(meta)) !== null) {
-		options[match[1]] = match[2] ?? match[3] ?? match[4] ?? '';
-	}
-
-	return options;
-}
-
-async function layoutSnippet(source) {
-	const key = createHash('sha256').update(source).digest('hex');
-	const cached = layoutCache.get(key);
-
-	if (cached) return cached;
-
-	const LikeC4 = await loadLikeC4();
-	const likec4 = await LikeC4.fromSource(source);
-
-	if (likec4.hasErrors()) {
-		// Only the first line of each error — LikeC4's parser errors enumerate
-		// every token it expected, which runs to hundreds of lines.
-		const detail = likec4
-			.getErrors()
-			.map((error) => String(error.message).split('\n')[0].trim())
-			.slice(0, 3)
-			.join('; ');
-
-		throw new Error(detail || 'the snippet could not be parsed');
-	}
-
-	const model = await likec4.layoutedModel();
-	// `$data` is the plain serialisable model; `$model` is its deprecated alias.
-	const dump = JSON.parse(JSON.stringify(model.$data));
-
-	const result = { dump, viewIds: Object.keys(dump.views ?? {}) };
-	layoutCache.set(key, result);
-
-	return result;
-}
-
-/** ESTree for `import <local> from '<source>';`, as the MDX compiler expects. */
-function importNode(local, source) {
-	return {
-		type: 'mdxjsEsm',
-		value: `import ${local} from ${JSON.stringify(source)};`,
-		data: {
-			estree: {
-				type: 'Program',
-				sourceType: 'module',
-				body: [
-					{
-						type: 'ImportDeclaration',
-						specifiers: [
-							{ type: 'ImportDefaultSpecifier', local: { type: 'Identifier', name: local } },
-						],
-						source: { type: 'Literal', value: source, raw: JSON.stringify(source) },
-						attributes: [],
-					},
-				],
-			},
-		},
-	};
-}
-
-function attributes(pairs) {
-	return Object.entries(pairs)
-		.filter(([, value]) => value !== undefined && value !== null && value !== '')
-		.map(([name, value]) => ({ type: 'mdxJsxAttribute', name, value: String(value) }));
-}
-
-function describe(fileURL) {
-	if (!fileURL) return 'a content file';
-
-	try {
-		return fileURLToPath(fileURL);
-	} catch {
-		return String(fileURL);
-	}
-}
-
-// region plugin
-/**
- * @returns {import('satteri').MdastPluginEntry}
- */
-export function likec4Fences() {
-	// A factory runs once per document, so `used` is safely per-file.
-	return (factory) => {
-		// Astro only supports components in .mdx. Leaving the fence as a code
-		// block is the graceful outcome, but say so — a silent code block where
-		// a diagram was intended is easy to miss in review.
-		if (factory.sourceFormat !== 'mdx') {
-			if (!factory.source.includes('```' + FENCE_LANG)) return null;
-
-			return {
-				name: 'likec4-fences:warn',
-				code(node, ctx) {
-					if (node.lang !== FENCE_LANG) return;
-
-					console.warn(
-						`[likec4-fences] ${describe(ctx.fileURL)} has a \`\`\`${FENCE_LANG} fence, but fences only ` +
-							'render as diagrams in .mdx files. Rename the page to .mdx, or use <LikeC4View /> directly.',
-					);
-				},
-			};
-		}
-
-		if (!factory.source.includes('```' + FENCE_LANG)) return null;
-
-		const used = new Set();
-
-		return {
-			name: 'likec4-fences',
-
-			async code(node, ctx) {
-				if (node.lang !== FENCE_LANG) return;
-
-				const where = `${describe(ctx.fileURL)}: \`\`\`${FENCE_LANG} fence`;
-				const options = parseFenceMeta(node.meta);
-				const source = (node.value ?? '').trim();
-
-				const common = {
-					title: options.title,
-					description: options.description,
-					height: options.height,
-					collapsible: options.collapsible,
-					defaultOpen: options.defaultOpen,
-				};
-
-				if (source.length === 0) {
-					if (!options.view) {
-						throw new Error(`${where} is empty, so it needs \`view="<id>"\` to name a view in the project model.`);
-					}
-
-					used.add(PROJECT_COMPONENT);
-
-					ctx.replaceNode(node, {
-						type: 'mdxJsxFlowElement',
-						name: PROJECT_COMPONENT,
-						attributes: attributes({ ...common, viewId: options.view }),
-						children: [],
-					});
-
-					return;
-				}
-
-				let layout;
-
-				try {
-					layout = await layoutSnippet(source);
-				} catch (error) {
-					throw new Error(`${where} is not valid LikeC4 — ${error.message}`);
-				}
-
-				const viewId = options.view ?? layout.viewIds[0];
-
-				if (!viewId || !layout.viewIds.includes(viewId)) {
-					throw new Error(
-						`${where} has no view "${viewId ?? '(none)'}". Declared: ${layout.viewIds.join(', ') || '(none)'}.`,
-					);
-				}
-
-				used.add(INLINE_COMPONENT);
-
-				ctx.replaceNode(node, {
-					type: 'mdxJsxFlowElement',
-					name: INLINE_COMPONENT,
-					attributes: attributes({ ...common, viewId, model: JSON.stringify(layout.dump) }),
-					children: [],
-				});
-			},
-
-			// Imports go in once, after every fence on the page is known.
-			after(root, ctx) {
-				if (used.size === 0) return;
-
-				ctx.insertChildAt(
-					root,
-					0,
-					[...used].map((local) => importNode(local, IMPORTS[local])),
-				);
-			},
-		};
-	};
-}
-// endregion
-
-export default likec4Fences;