void-plugin-hono-jsx 0.1.0-alpha.2 → 0.1.0-alpha.4

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "void-plugin-hono-jsx",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "private": false,
-  "description": "Experimental Hono JSX Pages adapter for Void 0.26.1",
+  "description": "Experimental Hono JSX Pages adapter for Void",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -28,12 +28,22 @@
     "./form": {
       "types": "./dist/server/form.d.ts",
       "default": "./dist/server/form.js"
+    },
+    "./markdown/plugin": {
+      "types": "./dist/plugins/hono-markdown.d.ts",
+      "import": "./dist/plugins/hono-markdown.js"
+    },
+    "./markdown": {
+      "types": "./dist/server/markdown.d.ts",
+      "default": "./dist/server/markdown.js"
     }
   },
   "peerDependencies": {
-    "hono": "4.13.13",
-    "void": "0.26.1",
-    "vite": "8.3.3"
+    "hono": ">=4.13.13 <5.0.0",
+    "void": ">=0.26.1 <0.28.0",
+    "vite": ">=8.0.16 <9.0.0",
+    "markdown-exit": ">=1.3.0 <2.0.0",
+    "yaml": ">=2.9.1 <3.0.0"
   },
   "repository": {
     "type": "git",
@@ -55,5 +65,13 @@
     "jsx",
     "vite",
     "ssr"
-  ]
+  ],
+  "peerDependenciesMeta": {
+    "markdown-exit": {
+      "optional": true
+    },
+    "yaml": {
+      "optional": true
+    }
+  }
 }

package/src/plugins/compatibility.ts

@@ -1,27 +1,64 @@
 import { createRequire } from 'node:module';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { version as helperViteVersion } from 'vite';
 
-const supported = { void: '0.26.1', hono: '4.13.13', vite: '8.3.3' };
-export function assertSupportedFrameworks() {
-  const require = createRequire(import.meta.url);
-  for (const [name, expected] of Object.entries(supported)) {
-    let directory = dirname(require.resolve(name));
-    let version: string | undefined;
-    while (true) {
-      const path = join(directory, 'package.json');
-      if (existsSync(path)) {
-        const metadata: unknown = JSON.parse(readFileSync(path, 'utf8'));
-        if (typeof metadata === 'object' && metadata !== null && 'name' in metadata && metadata.name === name) {
-          if (!('version' in metadata) || typeof metadata.version !== 'string') throw new Error(`Hono Pages: ${name} package version is missing.`);
-          version = metadata.version;
-          break;
-        }
+export const supportedFrameworkRanges = {
+  void: '>=0.26.1 <0.28.0',
+  hono: '>=4.13.13 <5.0.0',
+  vite: '>=8.0.16 <9.0.0',
+};
+export const supportedViteRange = supportedFrameworkRanges.vite;
+
+// Only stable releases are admitted. Void is pre-1.0, so its next minor
+// requires explicit validation; Hono and Vite use their current major lines.
+export function supportsFramework(name: keyof typeof supportedFrameworkRanges, version: unknown): boolean {
+  if (typeof version !== 'string') return false;
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(version);
+  if (!match) return false;
+  const [major, minor, patch] = match.slice(1).map(Number);
+  if (![major, minor, patch].every(Number.isSafeInteger)) return false;
+  if (name === 'void') return major === 0 && ((minor === 26 && patch >= 1) || minor === 27);
+  if (name === 'hono') return major === 4 && (minor > 13 || (minor === 13 && patch >= 13));
+  return major === 8 && (minor > 0 || patch >= 16);
+}
+export const supportsVite = (version: unknown): boolean => supportsFramework('vite', version);
+
+type PackageInfo = { version: string; path: string };
+function packageInfo(name: string, require: NodeRequire): PackageInfo {
+  let directory = dirname(require.resolve(name));
+  while (true) {
+    const path = join(directory, 'package.json');
+    if (existsSync(path)) {
+      const metadata: unknown = JSON.parse(readFileSync(path, 'utf8'));
+      if (typeof metadata === 'object' && metadata !== null && 'name' in metadata && (metadata.name === name || (name === 'vite' && metadata.name === '@voidzero-dev/vite-plus-core'))) {
+        if (!('version' in metadata) || typeof metadata.version !== 'string') throw new Error(`Hono Pages: ${name} package version is missing (${path}).`);
+        return { version: metadata.version, path };
       }
-      const parent = dirname(directory);
-      if (parent === directory) throw new Error(`Hono Pages: cannot locate ${name} package metadata.`);
-      directory = parent;
     }
-    if (version !== expected) throw new Error(`Hono Pages: ${name} ${version} is unverified; install ${name}@${expected}. The adapter requires void@0.26.1, hono@4.13.13 and vite@8.3.3.`);
+    const parent = dirname(directory);
+    if (parent === directory) throw new Error(`Hono Pages: cannot locate ${name} package metadata from ${require.resolve(name)}.`);
+    directory = parent;
+  }
+}
+function describe(name: string, require: NodeRequire): string {
+  try { const info = packageInfo(name, require); return `${info.path} (metadata ${info.version})`; }
+  catch { return `not resolved from ${require.resolve.paths(name)?.join(', ') ?? 'this context'}`; }
+}
+
+export function assertSupportedFrameworks({ root, viteVersion }: { root: string; viteVersion: unknown }) {
+  const adapter = createRequire(import.meta.url);
+  const project = createRequire(join(root, 'package.json'));
+  const diagnostic = () => `Running Vite from hook context: ${typeof viteVersion === 'string' ? viteVersion : 'unavailable'}. Adapter helper Vite: ${helperViteVersion}; package.json: ${describe('vite', adapter)}. Project Vite package.json: ${describe('vite', project)}. Package paths are diagnostics, not the running Vite identity.`;
+  if (!supportsVite(viteVersion)) {
+    throw new Error(`Hono Pages: running Vite ${typeof viteVersion === 'string' ? viteVersion : 'unavailable'} is unsupported; expected ${supportedViteRange}. ${diagnostic()} Update the CLI/launcher that executes Vite. For bundled launchers such as vp, installing project vite alone does not update the running Vite. For standard Vite, install vite@^8.3.4 and run vite directly.`);
+  }
+  if (!supportsVite(helperViteVersion)) {
+    throw new Error(`Hono Pages: adapter helper Vite ${helperViteVersion} is unsupported; expected ${supportedViteRange}. ${diagnostic()} Inspect the adapter's resolved peer copy; install vite@^8.3.4 and refresh the adapter's peer resolution/lockfile if a stale copy remains.`);
+  }
+  for (const name of ['void', 'hono'] as const) {
+    const expected = supportedFrameworkRanges[name];
+    const info = packageInfo(name, adapter);
+    if (!supportsFramework(name, info.version)) throw new Error(`Hono Pages: ${name} ${info.version} is unsupported; install ${name}@"${expected}". Resolved package.json: ${info.path}. Project package.json: ${describe(name, project)}. ${diagnostic()}`);
   }
 }

package/src/plugins/hono-islands.ts

@@ -1,30 +1,44 @@
 import { readFileSync, realpathSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { normalizePath, parseSync, type Plugin } from 'vite';
-import { scanPages, resolvePagesDir, type PageScanResult } from 'void/pages';
-import { findIslandImports, editIslandSource, resolveSpecifier, computePagesNeedingClientJS, ISLANDS_RENDERER_ID, ISLANDS_CLIENT_ENTRY_ID } from 'void/pages-islands-plugin';
+import { scanPages, resolveEffectiveLayoutChain, resolvePagesDir, type PageScanResult } from 'void/pages';
+import { findIslandImports, editIslandSource, computePagesNeedingClientJS, ISLANDS_RENDERER_ID, ISLANDS_CLIENT_ENTRY_ID } from 'void/pages-islands-plugin';
 
-/** Narrow adapter for Void's load-on-page-load island convention. */
+import { resolveComponent } from './resolve-component.ts';
+
+import { markdownApi, markdownDiagnostic, type HonoMarkdownApi } from './markdown-api.ts';
+
+/** Hono mounting through Void's shared island scheduler. */
 export function honoIslands(): Plugin {
   const root = process.cwd();
   const pagesDir = resolvePagesDir(root);
   const islands = new Map<string, string>();
   const pageFiles = new Set<string>();
+  const graph = new Map<string, Set<string>>();
+  const directlyInteractive = new Set<string>();
+  const interactivePages = new Set<string>();
+  const scriptOnlyPages = new Set<string>();
   let scan: PageScanResult | undefined;
+  let markdown: HonoMarkdownApi | undefined;
 
   function islandImports(code: string, filename: string) {
     const found = findIslandImports(code, filename);
     const attributed = parseSync(filename, code).program.body.filter((node) => node.type === 'ImportDeclaration' && node.attributes?.some(({ key }) => ('name' in key && key.name === 'island') || ('value' in key && key.value === 'island')));
-    if (attributed.length !== found.length) throw new Error(`Hono islands: use one default import with exactly one island: 'load' attribute in ${filename}.`);
+    if (attributed.length !== found.length) throw new Error(`Hono islands: use one default import with exactly one island attribute using load, visible, idle or media:query in ${filename}.`);
     return found;
   }
 
   function imports(code: string, filename: string) {
     const found = islandImports(code, filename);
     for (const entry of found) {
-      if (entry.hydrate !== 'load') throw new Error(`Hono islands: unsupported policy '${entry.hydrate}' in ${filename}; use island: 'load'.`);
+      if (!['load', 'visible', 'idle'].includes(entry.hydrate)) {
+        const query = entry.hydrate.startsWith('media:') ? entry.hydrate.slice(6).trim() : '';
+        let balance = 0;
+        for (const character of query) { if (character === '(') balance++; if (character === ')') balance--; if (balance < 0) break; }
+        if (!query || balance !== 0 || /[{};]/.test(query)) throw new Error(`Hono islands: unsupported policy or invalid media query '${entry.hydrate}' in ${filename}.`);
+      }
       if (!entry.specifier.startsWith('.')) throw new Error(`Hono islands: use a relative TSX/JSX component import in ${filename}.`);
-      const path = resolveSpecifier(entry.specifier, join(filename, '..'), ['.tsx', '.jsx']);
+      const path = resolveComponent(entry.specifier, join(filename, '..'), ['.tsx', '.jsx']);
       if (!path || !/\.[jt]sx$/.test(path)) throw new Error(`Hono islands: cannot resolve TSX/JSX component ${entry.specifier} in ${filename}.`);
       const canonical = realpathSync(path);
       const id = normalizePath(relative(root, canonical));
@@ -35,21 +49,79 @@ export function honoIslands(): Plugin {
 
   async function rescan() {
     scan = await scanPages(root, { pagesDir });
-    islands.clear();
-    pageFiles.clear();
+    // Never pass Markdown text to the JavaScript static-graph parser.
+    for (const file of [...scan.pages.map(page => page.componentPath), ...scan.layouts.map(layout => layout.filePath), ...scan.namedLayouts.map(layout => layout.filePath)]) {
+      if (/\.md$/.test(file) && !markdown) throw new Error(`${markdownDiagnostic} ${file}`);
+    }
+    islands.clear(); pageFiles.clear(); graph.clear(); directlyInteractive.clear(); interactivePages.clear(); scriptOnlyPages.clear();
+    const visit = (filename: string) => {
+      const canonical = realpathSync(filename);
+      if (graph.has(canonical)) return;
+      const dependencies = new Set<string>(); graph.set(canonical, dependencies); pageFiles.add(canonical);
+      const code = canonical.endsWith('.md') && markdown ? markdown.getGraphSource(canonical) : readFileSync(canonical, 'utf8');
+      const found = imports(code, canonical);
+      if (found.length) {
+        if (!/\.[jt]sx$/.test(canonical) && !(canonical.endsWith('.md') && markdown)) throw new Error('Hono islands: attributed imports require a static TSX/JSX module.');
+        directlyInteractive.add(canonical);
+      }
+      for (const node of parseSync(canonical, code).program.body) {
+        const source = node.type === 'ImportDeclaration' ? node.source : node.type === 'ExportNamedDeclaration' || node.type === 'ExportAllDeclaration' ? node.source : undefined;
+        const typeOnly = node.type === 'ImportDeclaration' ? node.importKind === 'type' || (node.specifiers.length > 0 && node.specifiers.every((entry) => entry.type === 'ImportSpecifier' && entry.importKind === 'type')) : (node.type === 'ExportNamedDeclaration' || node.type === 'ExportAllDeclaration') && node.exportKind === 'type';
+        if (!source || typeOnly || !source.value.startsWith('.') || found.some((entry) => entry.specifier === source.value)) continue;
+        const target = resolveComponent(source.value, join(canonical, '..'), ['.tsx', '.jsx', '.ts', '.js']);
+        if (!target || !/\.[jt]sx?$/.test(target)) continue;
+        dependencies.add(realpathSync(target)); visit(target);
+      }
+
+    };
+    for (const entry of [...scan.pages.filter((page) => page.island).map((page) => page.componentPath), ...scan.layouts.filter((layout) => layout.island).map((layout) => layout.filePath), ...scan.namedLayouts.filter((layout) => layout.island).map((layout) => layout.filePath)]) visit(join(pagesDir, entry));
+    const validateInteractive = (filename: string, seen = new Set<string>()) => {
+      const canonical = realpathSync(filename);
+      if (seen.has(canonical)) return; seen.add(canonical);
+      const code = canonical.endsWith('.md') && markdown ? markdown.getGraphSource(canonical) : readFileSync(canonical, 'utf8');
+      if (islandImports(code, canonical).length) throw new Error('Hono islands: attributed imports inside an interactive component are unsupported; use ordinary component imports there.');
+      for (const node of parseSync(canonical, code).program.body) {
+        const source = node.type === 'ImportDeclaration' ? node.source : node.type === 'ExportNamedDeclaration' || node.type === 'ExportAllDeclaration' ? node.source : undefined;
+        const typeOnly = node.type === 'ImportDeclaration' ? node.importKind === 'type' || (node.specifiers.length > 0 && node.specifiers.every((entry) => entry.type === 'ImportSpecifier' && entry.importKind === 'type')) : (node.type === 'ExportNamedDeclaration' || node.type === 'ExportAllDeclaration') && node.exportKind === 'type';
+        if (!source || typeOnly || !source.value.startsWith('.')) continue;
+        const target = resolveComponent(source.value, join(canonical, '..'), ['.tsx', '.jsx', '.ts', '.js']);
+        if (target && /\.[jt]sx?$/.test(target)) validateInteractive(target, seen);
+      }
+    };
+    for (const target of islands.values()) validateInteractive(target);
+    for (const page of scan.pages.filter((page) => !page.island)) {
+      for (const file of [page.componentPath, ...resolveEffectiveLayoutChain(page, scan.layouts, scan.namedLayouts).map((layout) => layout.filePath)]) validateInteractive(join(pagesDir, file));
+    }
+    const needsJS = new Set(directlyInteractive);
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const [file, dependencies] of graph) if (!needsJS.has(file) && [...dependencies].some((target) => needsJS.has(target))) { needsJS.add(file); changed = true; }
+    }
     for (const page of scan.pages.filter((page) => page.island)) {
-      const filename = realpathSync(join(pagesDir, page.componentPath));
-      pageFiles.add(filename);
-      imports(readFileSync(filename, 'utf8'), filename);
+      const files = [page.componentPath, ...resolveEffectiveLayoutChain(page, scan.layouts, scan.namedLayouts).map((layout) => layout.filePath)];
+      const hasIslands = files.some(file => needsJS.has(realpathSync(join(pagesDir, file))));
+      const hasScript = markdown?.getClientScripts().has(page.componentId);
+      if (hasIslands || hasScript) interactivePages.add(page.componentId);
+      if (hasScript && !hasIslands) scriptOnlyPages.add(page.componentId);
     }
   }
 
   return {
     name: 'void-hono:islands',
     enforce: 'pre',
+    configResolved(config) { markdown = markdownApi(config.plugins); },
     buildStart: rescan,
-    async hotUpdate({ file }) {
-      if (normalizePath(file).startsWith(normalizePath(pagesDir) + '/')) await rescan();
+    async hotUpdate({ file, modules, timestamp }) {
+      const inPages = normalizePath(file).startsWith(normalizePath(pagesDir) + '/');
+      if (!inPages && ![...pageFiles, ...islands.values()].some((path) => normalizePath(path) === normalizePath(file))) return;
+      await rescan();
+      const invalidated = new Set<(typeof modules)[number]>();
+      for (const id of [ISLANDS_RENDERER_ID, ISLANDS_CLIENT_ENTRY_ID, 'virtual:void-pages-renderer']) {
+        const module = this.environment.moduleGraph.getModuleById(`\0${id}`);
+        if (module) this.environment.moduleGraph.invalidateModule(module, invalidated, timestamp, true);
+      }
+      if (!inPages && this.environment.config.consumer === 'client') this.environment.hot.send({ type: 'full-reload' });
     },
     config() {
       return { build: { rollupOptions: { input: { 'islands-client': ISLANDS_CLIENT_ENTRY_ID } } } };
@@ -61,42 +133,68 @@ export function honoIslands(): Plugin {
       const filename = id.split('?')[0];
       if (!/\.[jt]sx$/.test(filename) || filename.includes('/node_modules/')) return;
       const canonical = realpathSync(filename);
-      if ((pageFiles.has(canonical) || [...islands.values()].includes(canonical)) && parseSync(filename, code).program.body.some((node) => node.type === 'ImportDeclaration' && node.source.value === 'void-plugin-hono-jsx/form')) {
-        throw new Error('Hono islands: form helpers are unsupported; use a full Pages component.');
+      if ((pageFiles.has(canonical) || [...islands.values()].includes(canonical)) && parseSync(filename, code).program.body.some((node) => node.type === 'ImportDeclaration' && node.importKind !== 'type' && ['void-plugin-hono-jsx/form', 'void-plugin-hono-jsx/pages'].includes(node.source.value) && node.specifiers.some((entry) => entry.type !== 'ImportSpecifier' ? node.source.value.endsWith('/form') : entry.importKind !== 'type' && ['useForm', 'action', 'setActionRouter'].includes('name' in entry.imported ? entry.imported.name : entry.imported.value)))) {
+        throw new Error('Hono islands: useForm/action require full Pages; use named useIslandForm/Form imports for islands.');
       }
       const found = islandImports(code, filename);
       if (!found.length) return;
-      if (!pageFiles.has(realpathSync(filename))) throw new Error('Hono islands: attributed imports are supported only directly in .island.tsx/.island.jsx pages.');
+      if (!pageFiles.has(canonical)) throw new Error('Hono islands: attributed imports require a static island page, layout or component graph; use ordinary imports inside interactive components.');
       imports(code, filename);
+      // Void requests static modules in the client environment to collect CSS.
+      // Actual interactive entry graphs were validated above; strip attributes
+      // for that traversal rather than generating server-only marker wrappers.
+      if (this.environment?.config.consumer === 'client') return editIslandSource(code, found.map((entry) => ({ start: entry.start, end: entry.end, text: `import ${entry.importName} from ${entry.specifierRaw};` })));
       return editIslandSource(code, found.map((entry) => {
-        const path = resolveSpecifier(entry.specifier, join(filename, '..'), ['.tsx', '.jsx']);
+        const path = resolveComponent(entry.specifier, join(filename, '..'), ['.tsx', '.jsx']);
         if (!path) throw new Error(`Hono islands: missing component ${entry.specifier}.`);
         const islandId = normalizePath(relative(root, realpathSync(path)));
         const component = `__honoIslandComponent${entry.start}`;
         return { start: entry.start, end: entry.end, text: `import ${component} from ${entry.specifierRaw};
-const ${entry.importName} = (props) => __honoIslandJsx('div', { 'data-island': ${JSON.stringify(islandId)}, 'data-hydrate': 'load', 'data-props': JSON.stringify(props), children: __honoIslandJsx(${component}, props) });` };
+const ${entry.importName} = (props) => __honoIslandJsx('div', { 'data-island': ${JSON.stringify(islandId)}, 'data-hydrate': ${JSON.stringify(entry.hydrate)}, 'data-props': JSON.stringify(props), children: __honoIslandJsx(${component}, props) });` };
       }), { prepend: "import { jsx as __honoIslandJsx } from 'hono/jsx/jsx-runtime';\n" });
     },
     load(id) {
       if (id === `\0${ISLANDS_RENDERER_ID}`) {
         if (!scan) throw new Error('Hono islands: page discovery has not completed.');
-        const interactive = [...computePagesNeedingClientJS(scan, pagesDir, null)];
+        const interactive = [...new Set([...computePagesNeedingClientJS(scan, pagesDir, null), ...interactivePages])];
         return `import { renderPage } from 'virtual:void-pages-renderer';
 const interactive = new Set(${JSON.stringify(interactive)});
+const scriptOnly = new Set(${JSON.stringify([...scriptOnlyPages])});
+const markdownScripts = new Set(${JSON.stringify([...(markdown?.getClientScripts().keys() ?? [])])});
 export function renderIslandPage(page, assets) {
   if (page.deferred?.length || page.deferredKeys) throw new Error('Hono islands: deferred props are unsupported.');
-  return renderPage(page, interactive.has(page.component) ? assets : { ...assets, preloads: '', body: '' });
+  if (!markdownScripts.has(page.component)) assets = { ...assets,
+    body: assets.body.replace(/<script\\b[^>]*src=["'][^"']*(?:void-hono-markdown-client|markdown-client-)[^"']*["'][^>]*>\\s*<\\/script>/g, ''),
+    preloads: assets.preloads.replace(/<link\\b[^>]*href=["'][^"']*markdown-client-[^"']*["'][^>]*>/g, ''),
+  };
+  if (!interactive.has(page.component)) return renderPage(page, { ...assets, preloads: '', body: '' });
+  if (scriptOnly.has(page.component)) {
+    // Keep the Markdown entry; its dynamic import loads only this page's code.
+    // Framework preloads and the island scheduler have no work on this chain.
+    const body = assets.body.replace(/<script\\b[^>]*src=["'][^"']*(?:void-islands-client|islands-client-)[^"']*["'][^>]*>\\s*<\\/script>/g, '');
+    return renderPage(page, { ...assets, preloads: '', body });
+  }
+  return renderPage(page, assets);
 }`;
       }
       if (id === `\0${ISLANDS_CLIENT_ENTRY_ID}`) {
-        if (!islands.size) return 'export {};';
+        if (!islands.size || !interactivePages.size) return 'export {};';
         const loaders = [...islands].map(([name, path]) => `${JSON.stringify(name)}: () => import(${JSON.stringify(path)})`).join(',\n');
-        return `import { initIslands } from 'void/pages-client';
+        return `${markdown ? "import { MarkdownContext } from 'void-plugin-hono-jsx/markdown';" : ''}
+import { initIslands } from 'void/pages-client';
 import { jsx } from 'hono/jsx/dom/jsx-runtime';
 import { render } from 'hono/jsx/dom';
+for (const element of document.querySelectorAll('[data-hydrate^="media:"]')) {
+  const query = element.getAttribute('data-hydrate').slice(6).trim();
+  if (matchMedia(query).media === 'not all' && query !== 'not all') throw new Error('Hono islands: invalid or unsupported media query ' + query);
+}
 initIslands({ ${loaders} }, (element, module, props) => {
   if (typeof module.default !== 'function') throw new Error('Hono islands: a component must export a default function.');
-  render(jsx(module.default, props), element);
+  let content = jsx(module.default, props);
+  ${markdown ? `const metadata = JSON.parse(document.getElementById('app')?.getAttribute('data-hono-markdown') || '{}');
+  const page = JSON.parse(document.getElementById('__VOID_PAGE_DATA__')?.textContent || '{}');
+  content = jsx(MarkdownContext.Provider, { value: { frontmatter: metadata.frontmatter ?? {}, headings: metadata.headings ?? [], props: page.props ?? {} }, children: content });` : ''}
+  render(content, element);
   element.setAttribute('data-hono-island', 'mounted');
 });`;
       }

package/src/plugins/hono-markdown.ts

@@ -0,0 +1,78 @@
+import { readFileSync, readdirSync, existsSync, realpathSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+import { normalizePath, type Plugin } from 'vite';
+import { resolvePagesDir } from 'void/pages';
+import { resolveComponent } from './resolve-component.ts';
+import { compileMarkdown, extractMarkdown, renderChunks } from './markdown-compiler.ts';
+import type { HonoMarkdownApi } from './markdown-api.ts';
+
+const clientId = 'virtual:void-hono-markdown-client';
+const scriptQuery = '?hono-markdown-script';
+const literal = (value: unknown) => `JSON.parse(${JSON.stringify(JSON.stringify(value))})`;
+
+/** Optional authored Markdown compiler; independent of @void/md private files. */
+export function voidHonoMarkdown(): Plugin {
+  let root = process.cwd();
+  let pagesDir = resolvePagesDir(root);
+  const scripts = new Map<string, string>();
+  const files = new Map<string, string>();
+  function rescan() {
+    scripts.clear(); files.clear();
+    if (!existsSync(pagesDir)) return;
+    for (const entry of readdirSync(pagesDir, { recursive: true, withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      const file = join(entry.parentPath, entry.name);
+      const id = normalizePath(relative(pagesDir, file)).replace(/\.md$/, '').replace(/\.island$/, '').replace(/\/index$/, '').replace(/^index$/, '') || 'index';
+      const { clientCode } = extractMarkdown(readFileSync(file, 'utf8'));
+      if (clientCode) { scripts.set(id, clientCode); files.set(id, file); }
+    }
+  }
+  const api: HonoMarkdownApi = { adapter: 'hono', clientEntryId: clientId, getClientScripts() { rescan(); return scripts; }, getGraphSource(file) { return extractMarkdown(readFileSync(file, 'utf8')).graphSource; } };
+  return {
+    // Void's Markdown entry/asset convention is shared with @void/md.
+    name: 'void-md', enforce: 'pre', api,
+    config() { return { build: { rollupOptions: { input: { 'markdown-client': clientId } } } }; },
+    configResolved(config) { if (!config.plugins.some(plugin => plugin.name === 'void-hono:pages')) throw new Error('Hono Markdown: configure voidHonoJsx() before voidHonoMarkdown().'); root = realpathSync(config.root); pagesDir = resolvePagesDir(root); rescan(); },
+    buildStart() { rescan(); },
+    hotUpdate({ file, timestamp }) {
+      if (!file.endsWith('.md') || !normalizePath(file).startsWith(normalizePath(pagesDir) + '/')) return;
+      rescan();
+      const entry = this.environment.moduleGraph.getModuleById(`\0${clientId}`);
+      if (entry) this.environment.moduleGraph.invalidateModule(entry, new Set(), timestamp, true);
+    },
+    resolveId(id) { if (id === clientId) return `\0${id}`; },
+    load(id) {
+      if (id.endsWith(scriptQuery)) return extractMarkdown(readFileSync(id.slice(0, -scriptQuery.length), 'utf8')).clientCode || 'export {};';
+      if (id !== `\0${clientId}`) return;
+      rescan();
+      if (!files.size) return 'export {};';
+      return `const scripts = {${[...files].map(([id, file]) => `${JSON.stringify(id)}: () => import(${JSON.stringify(normalizePath(file) + scriptQuery)})`).join(',')}};
+const id = document.getElementById('app')?.getAttribute('data-md-script');
+if (id && scripts[id]) await scripts[id]();`;
+    },
+    transform: {
+      filter: { id: /\.md$/ },
+      handler(source, id) {
+        const result = compileMarkdown(source);
+        const imports = result.imports.map((entry, index) => {
+          const target = resolveComponent(entry.specifier, dirname(id), ['.tsx', '.jsx']);
+          if (!target || !entry.specifier.startsWith('.')) throw new Error(`Hono Markdown: cannot resolve relative TSX/JSX island ${entry.specifier} in ${id}.`);
+          return { ...entry, alias: `__island${index}`, islandId: normalizePath(relative(root, realpathSync(target))) };
+        });
+        const chunks = renderChunks(result.html, new Set(imports.map(entry => entry.importName)));
+        const children = chunks.map(chunk => {
+          if ('html' in chunk) return `raw(${JSON.stringify(chunk.html)})`;
+          const entry = imports.find(entry => entry.importName === chunk.name)!;
+          const props = literal(chunk.props);
+          return `jsx('div', { 'data-island': ${JSON.stringify(entry.islandId)}, 'data-hydrate': ${JSON.stringify(entry.hydrate)}, 'data-props': JSON.stringify(${props}), children: jsx(${entry.alias}, ${props}) })`;
+        });
+        return { code: `import { jsx, Fragment } from 'hono/jsx/jsx-runtime';
+import { raw } from 'hono/html';
+${imports.map(entry => `import ${entry.alias} from ${JSON.stringify(entry.specifier)};`).join('\n')}
+export const frontmatter = ${literal(result.frontmatter)};
+export const headings = ${literal(result.headings)};
+export default function MarkdownPage() { return jsx(Fragment, { children: [${children.join(',')}] }); }`, map: null };
+      },
+    },
+  };
+}

package/src/plugins/hono-pages.ts

@@ -1,31 +1,57 @@
 import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { normalizePath } from 'vite';
-import { pagesRuntimePath, clientRuntimePath, publicRuntimeModules } from './runtime-paths.ts';
+import { pagesRuntimePath, clientRuntimePath, markdownRuntimePath, publicRuntimeModules } from './runtime-paths.ts';
 import { generateComponentManifest, resolvePagesDir, resolveStaticPageDataBuildOptions, scanPages, type PageScanResult } from 'void/pages';
 import type { Plugin } from 'vite';
+import { parseCacheFor, type CacheForInput } from 'void/pages-prefetch';
 import { honoJsx } from './hono-jsx.ts';
 import { honoIslands } from './hono-islands.ts';
+import { markdownApi, markdownDiagnostic, type HonoMarkdownApi } from './markdown-api.ts';
 import { assertSupportedFrameworks } from './compatibility.ts';
 
 const rendererId = 'virtual:void-pages-renderer';
 const clientId = 'virtual:void-pages-client';
 
-/** Experimental Pages contract verified against Void 0.26.1. */
-export function voidHonoPages(): Plugin[] {
+function assertComponentFile(file: string, kind: 'page' | 'layout', markdown = false) {
+  if (/\.md$/.test(file)) { if (markdown && kind === 'page') return; if (markdown) throw new Error('Hono Markdown: layouts must remain TSX/JSX: ' + file); throw new Error(`${markdownDiagnostic} ${kind}: ${file}`); }
+  if (!/\.[jt]sx$/.test(file)) throw new Error(`Hono Pages: only standard TSX/JSX ${kind}s are supported: ${file}.`);
+}
+
+
+export type HonoJsxOptions = {
+  viewTransitions?: boolean;
+  prefetch?: { hoverDelay?: number; cacheFor?: CacheForInput };
+};
+
+function clientOptions(options: HonoJsxOptions) {
+  const viewTransitions = options.viewTransitions ?? false;
+  const prefetchHoverDelay = options.prefetch?.hoverDelay ?? 75;
+  if (typeof viewTransitions !== 'boolean') throw new Error('Hono Pages: viewTransitions must be a boolean.');
+  if (!Number.isFinite(prefetchHoverDelay) || prefetchHoverDelay < 0) throw new Error('Hono Pages: prefetch.hoverDelay must be a finite non-negative number.');
+  const prefetchDefaultCacheFor = parseCacheFor(options.prefetch?.cacheFor ?? '30s');
+  if (![prefetchDefaultCacheFor.stale, prefetchDefaultCacheFor.expires].every(value => Number.isFinite(value) && value >= 0) || prefetchDefaultCacheFor.stale > prefetchDefaultCacheFor.expires) {
+    throw new Error('Hono Pages: prefetch.cacheFor must have finite non-negative durations, with stale <= expires.');
+  }
+  return { viewTransitions, prefetchHoverDelay, prefetchDefaultCacheFor };
+}
+
+/** Experimental Pages contract verified against Void 0.26.1 and 0.27.0. */
+export function voidHonoJsx(options: HonoJsxOptions = {}): Plugin[] {
+  const navigationOptions = clientOptions(options);
   const root = process.cwd();
   const pagesDir = resolvePagesDir(root);
   const staticData = resolveStaticPageDataBuildOptions(root);
   let scan: PageScanResult | undefined;
+  let markdown: HonoMarkdownApi | undefined;
 
   async function rescan() {
     scan = await scanPages(root, { pagesDir });
     for (const layout of [...scan.layouts, ...scan.namedLayouts]) {
-      if (layout.island || !/\.[jt]sx$/.test(layout.filePath)) throw new Error('Hono Pages: only standard TSX/JSX layouts are supported.');
+      assertComponentFile(layout.filePath, 'layout');
     }
     for (const page of scan.pages) {
-      if (!/\.[jt]sx$/.test(page.componentPath)) {
-        throw new Error(`Hono Pages: only standard TSX/JSX pages are supported: ${page.componentPath}.`);
-      }
+      assertComponentFile(page.componentPath, 'page', Boolean(markdown));
       if (staticData.enabled && page.methods.some((method) => method === 'action' || method === 'actions')) {
         throw new Error(`Hono Pages: actions require a server and cannot be used with static output: ${page.componentPath}.`);
       }
@@ -36,13 +62,19 @@ export function voidHonoPages(): Plugin[] {
   return [honoIslands(), honoJsx(), {
     name: 'void-hono:pages',
     enforce: 'pre',
-    config() {
-      assertSupportedFrameworks();
+    config(config) {
+      assertSupportedFrameworks({ root: resolve(config.root ?? root), viteVersion: this?.meta?.viteVersion });
       return {
         resolve: { dedupe: ['hono'] },
         build: { manifest: true, rollupOptions: { input: { 'pages-client': clientId } } },
       };
     },
+    configResolved: {
+      order: 'pre',
+      handler(config) {
+        markdown = markdownApi(config.plugins);
+      },
+    },
     configEnvironment() {
       const modules = Object.keys(publicRuntimeModules);
       const packages = [...new Set(modules.map((id) => id.slice(0, id.lastIndexOf('/'))))];
@@ -74,7 +106,7 @@ export function voidHonoPages(): Plugin[] {
     },
     resolveId(id) {
       if (id === rendererId || id === clientId) return `\0${id}`;
-      if (id === pagesRuntimePath || id === clientRuntimePath) return { id: realpathSync(id), external: false };
+      if (id === pagesRuntimePath || id === clientRuntimePath || id === markdownRuntimePath) return { id: realpathSync(id), external: false };
       const runtime = publicRuntimeModules[id];
       if (runtime) return { id: realpathSync(this.environment.config.consumer === 'client' ? runtime.client : runtime.server), external: false };
     },
@@ -83,7 +115,7 @@ export function voidHonoPages(): Plugin[] {
       const currentScan = scan ?? await rescan();
       const serverSnapshot = id === `\0${rendererId}` && this.environment.mode === 'dev';
       const manifestScan = id === `\0${clientId}`
-        ? { ...currentScan, pages: currentScan.pages.filter((page) => !page.island) }
+        ? { ...currentScan, pages: currentScan.pages.filter((page) => !page.island), layouts: currentScan.layouts.filter((layout) => !layout.island), namedLayouts: currentScan.namedLayouts.filter((layout) => !layout.island) }
         : serverSnapshot ? { ...currentScan, pages: currentScan.pages.filter((page) => page.renderMode !== 'client') } : currentScan;
       let manifest = generateComponentManifest(manifestScan, pagesDir);
       if (serverSnapshot) {
@@ -101,10 +133,13 @@ export function voidHonoPages(): Plugin[] {
       }
       if (id === `\0${clientId}` && !currentScan.pages.some((page) => !page.island)) return 'export {};';
       if (id === `\0${rendererId}`) {
+        const markdownScriptIds = [...(markdown?.getClientScripts().keys() ?? [])];
         return `
 import { jsx } from 'hono/jsx';
-import { createSsrRouter } from 'void/pages-client';
-import { PageContext, RouterContext } from ${JSON.stringify(pagesRuntimePath)};
+${markdown ? `import { MarkdownContext } from ${JSON.stringify(markdownRuntimePath)};` : ''}
+const markdownScriptIds = new Set(${JSON.stringify(markdownScriptIds)});
+import { createSsrRouter, idleNavigationState } from 'void/pages-client';
+import { PageContext, RouterContext, NavigationContext } from ${JSON.stringify(pagesRuntimePath)};
 import { serializePageData } from 'void/pages-server';
 import { renderHeadToString, renderHtmlAttrs, renderBodyAttrs } from 'void/pages-head';
 ${manifest}
@@ -112,7 +147,7 @@ export async function renderPage(pageObj, assetTags) {
   if (${JSON.stringify(staticData.enabled)} && pageObj.deferredKeys) throw new Error('Hono Pages: deferred props cannot be statically prerendered; remove defer().');
   const load = components[pageObj.component];
   if (!load) throw new Error('Hono Pages: unknown page component ' + pageObj.component);
-  const { default: Page } = await load();
+  const { default: Page, frontmatter = {}, headings = [] } = await load();
   if (typeof Page !== 'function') throw new Error('Hono Pages: a page must export a component function.');
   let content = jsx(Page, pageObj.props);
   const ids = layoutTree[pageObj.component] ?? [];
@@ -121,21 +156,23 @@ export async function renderPage(pageObj, assetTags) {
     if (typeof Layout !== 'function') throw new Error('Hono Pages: a layout must export a component function.');
     content = jsx(Layout, { children: content });
   }
-  const markup = await jsx(RouterContext.Provider, { value: createSsrRouter(pageObj.url, pageObj.params), children: jsx(PageContext.Provider, { value: pageObj, children: content }) }).toString();
+  ${markdown ? 'content = jsx(MarkdownContext.Provider, { value: { frontmatter, headings, props: pageObj.props }, children: content });' : ''}
+  const markup = await jsx(RouterContext.Provider, { value: createSsrRouter(pageObj.url, pageObj.params), children: jsx(PageContext.Provider, { value: pageObj, children: jsx(NavigationContext.Provider, { value: idleNavigationState(), children: content }) }) }).toString();
+  const appHtml = await jsx('div', { id: 'app', 'data-md-script': markdownScriptIds.has(pageObj.component) ? pageObj.component : undefined, ${markdown ? "'data-hono-markdown': JSON.stringify({ frontmatter, headings })," : ''} dangerouslySetInnerHTML: { __html: markup } }).toString();
   const head = pageObj.head;
   const body = pageObj.deferredKeys ? assetTags.body.replaceAll('<script type="module"', '<script async type="module"') : assetTags.body;
   return '<!doctype html><html' + (head ? renderHtmlAttrs(head) : '') + '><head>'
     + (head ? renderHeadToString(head) : '') + assetTags.css + assetTags.preloads
     + '</head><body' + (head ? renderBodyAttrs(head) : '') + '>'
     + '<script id="__VOID_PAGE_DATA__" type="application/json">' + serializePageData(pageObj) + '</script>'
-    + '<div id="app">' + markup + '</div>' + body + '</body></html>';
+    + appHtml + body + '</body></html>';
 }
 `;
       }
       return `
 import { startHonoPages } from ${JSON.stringify(clientRuntimePath)};
 ${manifest}
-await startHonoPages({ components, layoutTree, routeMeta, matchRoute, staticPageData: ${JSON.stringify(staticData.enabled)}, staticPageDataFastPath: ${JSON.stringify(staticData.fastPath)} });
+await startHonoPages({ components, layoutTree, routeMeta, matchRoute, staticPageData: ${JSON.stringify(staticData.enabled)}, staticPageDataFastPath: ${JSON.stringify(staticData.fastPath)} }, ${JSON.stringify(navigationOptions)});
 `;
     },
   }];

package/src/plugins/markdown-api.ts

@@ -0,0 +1,17 @@
+import type { Plugin } from 'vite';
+
+export const markdownDiagnostic = 'Hono Pages: Markdown requires voidHonoMarkdown() from void-plugin-hono-jsx/markdown/plugin and its optional parser dependencies. See docs/markdown.md.';
+export type HonoMarkdownApi = {
+  adapter: 'hono';
+  clientEntryId: string;
+  getClientScripts(): Map<string, string>;
+  getGraphSource(file: string): string;
+};
+export function markdownApi(plugins: readonly Plugin[]): HonoMarkdownApi | undefined {
+  const markdown = plugins.filter(plugin => plugin.name === 'void-md');
+  if (markdown.length > 1) throw new Error('Hono Pages: configure only one Markdown compiler.');
+  const plugin = markdown[0];
+  if (!plugin) return;
+  if (plugin.api?.adapter !== 'hono') throw new Error('Hono Pages: use voidHonoMarkdown(), not @void/md/plugin; the official compiler does not emit Hono components.');
+  return plugin.api as HonoMarkdownApi;
+}