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

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,32 +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';
 
+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 voidHonoPages(): Plugin[] {
+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}.`);
       }
@@ -44,6 +69,12 @@ export function voidHonoPages(): Plugin[] {
         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('/'))))];
@@ -75,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 };
     },
@@ -84,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) {
@@ -102,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}
@@ -113,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] ?? [];
@@ -122,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;
+}

package/src/plugins/markdown-compiler.ts

@@ -0,0 +1,77 @@
+import MarkdownExit from 'markdown-exit';
+import { parseSync } from 'vite';
+import { parseDocument } from 'yaml';
+import { findIslandImports, editIslandSource } from 'void/pages-islands-plugin';
+
+const unescapeAttribute = new MarkdownExit().utils.unescapeAll;
+
+export type Heading = { depth: number; slug: string; text: string };
+export function extractMarkdown(source: string) {
+  const match = source.match(/^<script\b[^>]*>([\s\S]*?)<\/script>\s*\n?/);
+  const script = match?.[1] ?? '';
+  const body = match ? source.slice(match[0].length) : source;
+  const imports = findIslandImports(script, 'markdown-script.ts');
+  const attributed = parseSync('markdown-script.ts', script).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 !== imports.length) throw new Error('Hono Markdown: use one default component import with exactly one island attribute.');
+  const graphSource = imports.map(entry => script.slice(entry.start, entry.end)).join('\n');
+  const clientCode = editIslandSource(script, imports.map(entry => ({ start: entry.start, end: entry.end, text: '' }))).code.trim();
+  return { body, script, imports, graphSource, clientCode };
+}
+
+export function compileMarkdown(source: string) {
+  const extracted = extractMarkdown(source);
+  const match = extracted.body.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  let frontmatter: Record<string, unknown> = {};
+  if (match) {
+    const yaml = parseDocument(match[1], { uniqueKeys: true });
+    if (yaml.errors.length) throw new Error('Hono Markdown: invalid frontmatter: ' + yaml.errors.map(error => error.message).join('; '));
+    const value: unknown = yaml.toJS({ maxAliasCount: 50 });
+    if (value !== null && (typeof value !== 'object' || Array.isArray(value))) throw new Error('Hono Markdown: frontmatter must be a mapping.');
+    frontmatter = (value ?? {}) as Record<string, unknown>;
+    try { JSON.stringify(frontmatter); } catch { throw new Error('Hono Markdown: frontmatter must be JSON serializable.'); }
+  }
+  const content = match ? extracted.body.slice(match[0].length) : extracted.body;
+  const compiler = new MarkdownExit({ html: true, linkify: true });
+  const tokens = compiler.parse(content, {});
+  const headings: Heading[] = [];
+  const slugs = new Map<string, number>();
+  const authoredHtml = tokens.flatMap(token => token.type === 'html_block' || token.type === 'html_inline' ? [token.content] : (token.children ?? []).filter(child => child.type === 'html_inline').map(child => child.content)).join('\n');
+  const usedIds = new Set([...authoredHtml.matchAll(/\bid\s*=\s*(?:"([^"]*)"|'([^']*)')/g)].map(match => match[1] ?? match[2]));
+  for (let index = 0; index < tokens.length; index++) {
+    if (tokens[index].type !== 'heading_open') continue;
+    const inline = tokens[index + 1];
+    const text = inline.children?.map(token => token.type === 'text' || token.type === 'code_inline' ? token.content : token.type === 'image' ? token.content : '').join('') ?? inline.content;
+    const base = text.toLowerCase().replace(/[^\p{L}\p{N} _-]/gu, '').trim().replace(/\s+/g, '-') || 'heading';
+    let count = slugs.get(base) ?? 0;
+    let slug = count ? `${base}-${count}` : base;
+    while (usedIds.has(slug)) { count++; slug = `${base}-${count}`; }
+    slugs.set(base, count + 1); usedIds.add(slug);
+    tokens[index].attrSet('id', slug);
+    headings.push({ depth: Number(tokens[index].tag.slice(1)), slug, text });
+  }
+  return { ...extracted, frontmatter, headings, html: compiler.renderer.render(tokens, compiler.options, {}) };
+}
+
+// Component tag splitting follows @void/md 0.27.0's emit-shared convention.
+// Hono raw fragments preserve enclosing HTML across the component boundaries.
+export function renderChunks(html: string, names: Set<string>) {
+  const tags = /<([A-Z]\w*)\s*((?:[^>/"']|"[^"]*"|'[^']*')*)\/\s*>|<([A-Z]\w*)\s*((?:[^>/"']|"[^"]*"|'[^']*')*)>([\s\S]*?)<\/\3\s*>/g;
+  const chunks: Array<{ html: string } | { name: string; props: Record<string, string | boolean> }> = [];
+  let cursor = 0;
+  for (const match of html.matchAll(tags)) {
+    const name = match[1] ?? match[3];
+    if (!names.has(name)) continue;
+    if (match[5]?.trim()) throw new Error('Hono Markdown: island tag children are unsupported; pass literal attributes to a self-closing tag.');
+    if (match.index > cursor) chunks.push({ html: html.slice(cursor, match.index) });
+    const props: Record<string, string | boolean> = Object.create(null);
+    const attrs = match[2] ?? match[4] ?? '';
+    const attrRe = /(\w[\w-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s]+)))?/g;
+    for (const attr of attrs.matchAll(attrRe)) {
+      const value = attr[2] ?? attr[3] ?? attr[4];
+      props[attr[1]] = value === undefined ? true : unescapeAttribute(value);
+    }
+    chunks.push({ name, props }); cursor = match.index + match[0].length;
+  }
+  if (cursor < html.length) chunks.push({ html: html.slice(cursor) });
+  return chunks;
+}

package/src/plugins/resolve-component.ts

@@ -0,0 +1,12 @@
+import { statSync } from 'node:fs';
+import { resolveSpecifier } from 'void/pages-islands-plugin';
+
+/** Relative component imports also use Vite's directory/index convention. */
+export function resolveComponent(specifier: string, importerDir: string, extensions: string[]) {
+  const target = resolveSpecifier(specifier, importerDir, extensions);
+  if (!target) return null;
+  if (statSync(target).isFile()) return target;
+  if (!statSync(target).isDirectory()) return null;
+  const index = resolveSpecifier('./index', target, extensions);
+  return index && statSync(index).isFile() ? index : null;
+}

package/src/plugins/runtime-paths.ts

@@ -5,7 +5,9 @@ import { fileURLToPath } from 'node:url';
 const compiled = new URL(import.meta.url).pathname.endsWith('.js');
 export const pagesRuntimePath = fileURLToPath(new URL(compiled ? '../server/pages.js' : '../runtime/pages.tsx', import.meta.url));
 export const clientRuntimePath = fileURLToPath(new URL(compiled ? '../browser/client.js' : '../runtime/client.tsx', import.meta.url));
+export const markdownRuntimePath = fileURLToPath(new URL(compiled ? '../server/markdown.js' : '../runtime/markdown.ts', import.meta.url));
 export const publicRuntimeModules: Record<string, { server: string; client: string }> = compiled ? {
+  'void-plugin-hono-jsx/markdown': { server: markdownRuntimePath, client: fileURLToPath(new URL('../browser/markdown.js', import.meta.url)) },
   'void-plugin-hono-jsx/pages': { server: pagesRuntimePath, client: fileURLToPath(new URL('../browser/pages.js', import.meta.url)) },
   'void-plugin-hono-jsx/form': {
     server: fileURLToPath(new URL('../server/form.js', import.meta.url)),