@ozsarman/clarityjs 0.6.0

package/src/typegen.js

@@ -0,0 +1,240 @@
+/**
+ * Clarity.js TypeScript Declaration Generator
+ *
+ * Produces .d.ts files from a Clarity AST.
+ * This gives IDE autocomplete, error checking, and documentation
+ * for Clarity components used in TypeScript projects.
+ *
+ * Generated types include:
+ *   - Component function signatures with prop types
+ *   - Signal types for all state/computed declarations
+ *   - AI contract annotations as JSDoc
+ *   - Lifecycle hook presence as documentation
+ *
+ * Author: Claude (Anthropic)
+ */
+
+// ─── Type Inference ───────────────────────────────────────────────────────────
+
+/**
+ * Infer a TypeScript type from a Clarity literal/expression node.
+ * We can't always know the type statically, so we fall back to 'unknown'.
+ */
+function inferType(node) {
+  if (!node) return 'unknown';
+
+  switch (node.type) {
+    case 'Literal':
+      if (typeof node.value === 'number')  return 'number';
+      if (typeof node.value === 'string')  return 'string';
+      if (typeof node.value === 'boolean') return 'boolean';
+      if (node.value === null)             return 'null';
+      return 'unknown';
+
+    case 'ArrayExpr':
+      if (node.elements.length === 0) return 'unknown[]';
+      // Infer from first element
+      return `${inferType(node.elements[0])}[]`;
+
+    case 'ObjectExpr':
+      if (node.properties.length === 0) return 'Record<string, unknown>';
+      const props = node.properties.map(p => `${p.key}: ${inferType(p.value)}`).join('; ');
+      return `{ ${props} }`;
+
+    case 'BinaryExpr':
+      // Arithmetic → number, comparison → boolean, string concat → string
+      if (['+', '-', '*', '/', '%'].includes(node.op)) return 'number';
+      if (['===', '!==', '==', '!=', '<', '>', '<=', '>=', '&&', '||'].includes(node.op)) return 'boolean';
+      return 'unknown';
+
+    case 'TernaryExpr':
+      return inferType(node.then);
+
+    case 'Ident':
+      // Can't know the type of an identifier without tracking scope
+      return 'unknown';
+
+    case 'CallExpr':
+      return 'unknown';
+
+    default:
+      return 'unknown';
+  }
+}
+
+/**
+ * Convert a Clarity param type annotation to a TypeScript type.
+ * Clarity uses: String, Number, Boolean, Array, Object
+ */
+function mapParamType(clarityType) {
+  if (!clarityType) return 'unknown';
+  const map = {
+    'String':    'string',
+    'Number':    'number',
+    'Boolean':   'boolean',
+    'Array':     'unknown[]',
+    'Object':    'Record<string, unknown>',
+    'Function':  '(...args: unknown[]) => unknown',
+    'Any':       'unknown',
+    'Node':      'HTMLElement | null',
+    'Signal':    'Signal<unknown>',
+    'Computed':  'Computed<unknown>',
+    'Context':   'ClarityContext<unknown>',
+  };
+  return map[clarityType] ?? clarityType;
+}
+
+/**
+ * Map a Clarity type annotation string that may include generics.
+ * e.g. "Signal<Number>" → "Signal<number>"
+ */
+function mapParamTypeGeneric(clarityType) {
+  if (!clarityType) return 'unknown';
+  // Handle generics: Signal<String> → Signal<string>
+  const generic = clarityType.match(/^(\w+)<(.+)>$/);
+  if (generic) {
+    const outer = mapParamType(generic[1]);
+    const inner = mapParamTypeGeneric(generic[2]);
+    return `${outer.replace('unknown', '')}${outer.includes('<') ? inner : `<${inner}>`}`;
+  }
+  return mapParamType(clarityType);
+}
+
+// ─── Type Generator ───────────────────────────────────────────────────────────
+
+export class TypeGenerator {
+  constructor(options = {}) {
+    this.runtimePath = options.runtimePath ?? '@ozsarman/clarityjs/src/runtime.js';
+  }
+
+  /**
+   * Generate a complete .d.ts file from the AST.
+   */
+  generate(ast, options = {}) {
+    const { filename = '<anonymous>' } = options;
+
+    const lines = [];
+
+    // Header
+    lines.push(`// Type declarations generated by Clarity.js compiler v0.3`);
+    lines.push(`// Source: ${filename}`);
+    lines.push(`// DO NOT EDIT — edit the .clarity source file instead`);
+    lines.push('');
+
+    // Import Signal/Computed/Context types from runtime
+    lines.push(`import type { Signal, Computed } from '${this.runtimePath}';`);
+    lines.push('');
+    // ClarityContext type — inline since it's small
+    lines.push(`/** Context token created by createContext() */`);
+    lines.push(`interface ClarityContext<T> { id: symbol; _type: 'context'; _default: T; }`);
+    lines.push('');
+
+    // One declaration block per component
+    for (const comp of ast.components) {
+      lines.push(...this._genComponentTypes(comp));
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  _genComponentTypes(comp) {
+    const lines = [];
+    const stateDecls    = comp.body.filter(n => n.type === 'StateDecl');
+    const computedDecls = comp.body.filter(n => n.type === 'ComputedDecl');
+    const effectDecls   = comp.body.filter(n => n.type === 'EffectDecl');
+    const aiDecls       = comp.body.filter(n => n.type === 'AIDecl');
+    const beforeMount   = comp.body.some(n => n.type === 'BeforeMountBlock');
+    const onMount       = comp.body.some(n => n.type === 'OnMountBlock');
+    const onCleanup     = comp.body.some(n => n.type === 'OnCleanupBlock');
+
+    // ── Generic type parameter string e.g. "<T, U extends string>" ──
+    const typeParams = comp.typeParams ?? [];
+    const typeParamStr = typeParams.length > 0
+      ? `<${typeParams.map(p => p.constraint ? `${p.name} extends ${p.constraint}` : p.name).join(', ')}>`
+      : '';
+    // For the Props interface name we use <T> without constraints: e.g. ListProps<T>
+    const typeParamRef = typeParams.length > 0
+      ? `<${typeParams.map(p => p.name).join(', ')}>`
+      : '';
+
+    // ── Props interface ──
+    const propsName = `${comp.name}Props`;
+    // Always emit a Props interface (even for zero-param components) so
+    // consumers can extend it and for consistent tooling output.
+    lines.push(`export interface ${propsName}${typeParamStr} {`);
+    for (const param of comp.params) {
+      const tsType  = mapParamTypeGeneric(param.type);
+      // A param with a default value is optional; without default it is required.
+      const hasDefault = param.default !== undefined && param.default !== null;
+      const optional   = hasDefault ? '?' : '';
+      // Inline JSDoc from inferred type
+      const inferredComment = param.type ? `` : ` // inferred: ${inferType(param.default)}`;
+      lines.push(`  ${param.name}${optional}: ${tsType};${inferredComment}`);
+    }
+    lines.push(`  /** Children passed as <${comp.name}>...</${comp.name}> */`);
+    lines.push(`  children?: Node | Node[];`);
+    lines.push(`}`);
+    lines.push('');
+
+    // ── AI Contract (as JSDoc) ──
+    const jsdocLines = [];
+    if (beforeMount) jsdocLines.push(` * @lifecycle beforeMount — runs after render, before DOM insertion`);
+    if (onMount)   jsdocLines.push(` * @lifecycle onMount — runs after DOM insertion`);
+    if (onCleanup) jsdocLines.push(` * @lifecycle onCleanup — runs on unmount, disposes all effects`);
+    for (const ai of aiDecls) {
+      jsdocLines.push(` * @ai:${ai.capability} [${ai.targets.join(', ')}]`);
+    }
+    if (typeParams.length > 0) {
+      for (const tp of typeParams) {
+        const constraint = tp.constraint ? ` (extends ${tp.constraint})` : '';
+        jsdocLines.push(` * @typeParam ${tp.name}${constraint}`);
+      }
+    }
+
+    if (jsdocLines.length > 0) {
+      lines.push(`/**`);
+      lines.push(` * ${comp.name} component`);
+      jsdocLines.forEach(l => lines.push(l));
+      lines.push(` */`);
+    }
+
+    // ── Component function — with generics if declared ──
+    const propsRef = `${propsName}${typeParamRef}`;
+    lines.push(`export declare function ${comp.name}${typeParamStr}(props?: ${propsRef}): HTMLElement;`);
+    lines.push(`export default ${comp.name}${typeParamStr};`);
+    lines.push('');
+
+    // ── Internal signal types (useful for testing / advanced tooling) ──
+    if (stateDecls.length > 0 || computedDecls.length > 0) {
+      lines.push(`/** Internal signals exposed for testing and AI tooling */`);
+      lines.push(`export interface ${comp.name}Internals {`);
+
+      for (const s of stateDecls) {
+        const t = inferType(s.init);
+        lines.push(`  /** state ${s.name} = ${t} */`);
+        lines.push(`  ${s.name}: Signal<${t}>;`);
+      }
+      for (const c of computedDecls) {
+        const t = inferType(c.expr);
+        lines.push(`  /** computed ${c.name} */`);
+        lines.push(`  ${c.name}: Computed<${t}>;`);
+      }
+
+      // AI contract in internals
+      for (const ai of aiDecls) {
+        lines.push(`  /** ai:${ai.capability} [${ai.targets.join(', ')}] */`);
+        lines.push(`  __ai_${ai.capability}__: readonly string[];`);
+      }
+
+      lines.push(`}`);
+    }
+
+    return lines;
+  }
+}
+
+// ─── Convenience export ───────────────────────────────────────────────────────
+export function generateTypes(ast, options = {}) {
+  return new TypeGenerator(options).generate(ast, options);
+}

package/src/vite-plugin.js

@@ -0,0 +1,447 @@
+/**
+ * Clarity.js Vite Plugin — with Stateful HMR + Route-level Code Splitting
+ *
+ * Integrates .clarity files into Vite. On file change:
+ *   1. Recompiles the .clarity file
+ *   2. Uses Vite's HMR API to hot-swap the module
+ *   3. Re-mounts components PRESERVING their signal state
+ *
+ * Stateful HMR strategy:
+ *   - Before hot swap: snapshot all signal values from mounted components
+ *   - After swap: re-mount with the snapshot values as initial state
+ *   - This means state survives code changes — only the template/logic updates
+ *
+ * Route-level code splitting (opt-in via codeSplitting: true):
+ *   - Files in pages/ are automatically placed in separate Rollup chunks
+ *   - Each route chunk is named route-<slug>.js for human-readable filenames
+ *   - A route manifest (clarity-route-manifest.json) is emitted to disk
+ *   - <link rel="modulepreload"> tags are injected for the current route chunk
+ *   - Link hover → prefetch via import() before the user even clicks
+ *
+ * Usage in vite.config.js:
+ *   import clarityPlugin from '@ozsarman/clarityjs/vite'
+ *   export default { plugins: [clarityPlugin({ codeSplitting: true, pagesDir: 'pages' })] }
+ *
+ * Author: Claude (Anthropic)
+ */
+
+import { compile } from './index.js';
+import { extractStyles, scopeCSS, injectScopeAttr, collectStyles, cssModules } from './scoped-css.js';
+import { filePathToRoutePattern, routeScore } from './pages-router.js';
+import { resolve, relative, join, basename } from 'node:path';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+
+// ─── virtual:clarity-pages ────────────────────────────────────────────────────
+const VIRTUAL_PAGES_ID         = 'virtual:clarity-pages';
+const RESOLVED_VIRTUAL_PAGES   = '\0' + VIRTUAL_PAGES_ID;
+
+// Special page files that are NOT routes (conventions / layout).
+const PAGE_SPECIAL_BASENAMES = new Set(['loading', 'error', 'not-found', '_layout']);
+
+function _isSpecialPageFile(file) {
+  const base = basename(file).replace(/\.(clarity|jsx?|mjs|tsx?)$/i, '');
+  return PAGE_SPECIAL_BASENAMES.has(base) || base.startsWith('_');
+}
+
+/** Find a convention file (loading/error/not-found) at the pages root, if any. */
+function _findConvention(pagesAbs, name) {
+  for (const ext of ['clarity', 'js', 'mjs', 'ts', 'tsx', 'jsx']) {
+    const p = join(pagesAbs, `${name}.${ext}`);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Generate the source of the `virtual:clarity-pages` module: a lazy, code-split
+ * route table plus a ready-to-mount `Routes` component.
+ */
+function _generatePagesModule(pagesAbs, runtimePagesImport = '@ozsarman/clarityjs/pages-router') {
+  if (!existsSync(pagesAbs)) {
+    return `import { createPagesRouter } from '${runtimePagesImport}';\n` +
+      `export const routes = [];\n` +
+      `export const Routes = createPagesRouter({ routes });\n` +
+      `export default Routes;\n`;
+  }
+
+  const files = _scanPageFiles(pagesAbs).filter(f => !_isSpecialPageFile(f));
+
+  // Build route entries (sorted most-specific first for deterministic output).
+  const entries = files
+    .map(file => ({ file, rel: relative(pagesAbs, file).replace(/\\/g, '/') }))
+    .map(e => ({ ...e, pattern: filePathToRoutePattern(e.rel) }))
+    .sort((a, b) => routeScore(b.pattern) - routeScore(a.pattern));
+
+  const routeLines = entries.map(e =>
+    `  { pattern: ${JSON.stringify(e.pattern)}, file: ${JSON.stringify(e.rel)}, ` +
+    `load: () => import(${JSON.stringify(e.file)}) },`
+  ).join('\n');
+
+  // Convention components (eager — they are small and shown synchronously).
+  const loadingFile  = _findConvention(pagesAbs, 'loading');
+  const errorFile    = _findConvention(pagesAbs, 'error');
+  const notFoundFile = _findConvention(pagesAbs, 'not-found');
+
+  const imports = [`import { createPagesRouter } from '${runtimePagesImport}';`];
+  const opts = ['routes'];
+  if (loadingFile)  { imports.push(`import _Loading from ${JSON.stringify(loadingFile)};`);   opts.push('loading: _Loading'); }
+  if (errorFile)    { imports.push(`import _Error from ${JSON.stringify(errorFile)};`);       opts.push('error: _Error'); }
+  if (notFoundFile) { imports.push(`import _NotFound from ${JSON.stringify(notFoundFile)};`); opts.push('notFound: _NotFound'); }
+
+  return [
+    '// Generated by clarity-js Vite plugin (scanPages) — do not edit.',
+    ...imports,
+    '',
+    'export const routes = [',
+    routeLines,
+    '];',
+    '',
+    `export const Routes = createPagesRouter({ ${opts.join(', ')} });`,
+    'export default Routes;',
+    '',
+  ].join('\n');
+}
+
+// ─── HMR client code (appended to every compiled .clarity module) ─────────────
+// This runs in the browser and wires up Vite's HMR callbacks.
+const HMR_CLIENT_RUNTIME = `
+// ── Clarity Stateful HMR ────────────────────────────────────────────────────
+if (import.meta.hot) {
+  // Registry: maps component name → { element, unmount, props }
+  // Populated by the patched mount() call below.
+  const _hmrRegistry = new Map();
+
+  // Intercept mount() to track all mounted components
+  const _origMount = typeof mount !== 'undefined' ? mount : null;
+  if (_origMount) {
+    globalThis.__clarity_hmr_mount__ = function(ComponentFn, container, props) {
+      const unmount = _origMount(ComponentFn, container, props);
+      const name = ComponentFn.name || ComponentFn.displayName || 'Unknown';
+      _hmrRegistry.set(name, { ComponentFn, container, props: props ?? {}, unmount });
+      return unmount;
+    };
+  }
+
+  import.meta.hot.accept((newModule) => {
+    if (!newModule) return;
+
+    for (const [name, entry] of _hmrRegistry) {
+      const NewComponent = newModule[name] ?? newModule.default;
+      if (!NewComponent) continue;
+
+      // 1. Snapshot current AI-readable state (if any)
+      let snapshot = {};
+      try {
+        const rootEl = entry.container.firstElementChild;
+        if (rootEl?.__clarity_ai__) snapshot = rootEl.__clarity_ai__.snapshot();
+      } catch (_) {}
+
+      // 2. Unmount the old component
+      try { entry.unmount(); } catch (_) {}
+
+      // 3. Re-mount the new component — merge snapshot into props as initial values
+      const newProps = { ...entry.props, ...snapshot };
+      const unmount  = (globalThis.__clarity_hmr_mount__ ?? _origMount)(NewComponent, entry.container, newProps);
+
+      // 4. Update registry with new component fn and unmount handle
+      _hmrRegistry.set(name, { ...entry, ComponentFn: NewComponent, unmount });
+
+      console.log(\`[Clarity HMR] 🔥 \${name} updated (state preserved)\`);
+    }
+  });
+
+  import.meta.hot.dispose(() => {
+    for (const { unmount } of _hmrRegistry.values()) {
+      try { unmount(); } catch (_) {}
+    }
+    _hmrRegistry.clear();
+  });
+}
+// ────────────────────────────────────────────────────────────────────────────
+`;
+
+// ─── Plugin ───────────────────────────────────────────────────────────────────
+/**
+ * @param {object} opts
+ * @param {string}  opts.runtimePath   — what the compiled JS imports from (default: '@ozsarman/clarityjs/runtime')
+ * @param {string}  opts.routerPath    — what the compiled JS imports router from (default: '@ozsarman/clarityjs/router')
+ * @param {boolean} opts.sourceMap     — emit source maps (default: follows Vite mode)
+ * @param {boolean} opts.types         — emit .d.ts on build (default: false)
+ * @param {boolean} opts.hmr           — enable stateful HMR (default: true)
+ * @param {boolean} opts.verbose       — log compile times (default: false)
+ * @param {boolean} opts.codeSplitting — split pages/ into separate route chunks (default: false)
+ * @param {string}  opts.pagesDir      — relative path to pages directory (default: 'pages')
+ */
+export default function clarityPlugin(opts = {}) {
+  const {
+    runtimePath   = '@ozsarman/clarityjs/runtime',
+    routerPath    = '@ozsarman/clarityjs/router',
+    pagesRouterPath = '@ozsarman/clarityjs/pages-router',
+    types         = false,
+    hmr           = true,
+    verbose       = false,
+    codeSplitting = false,
+    scanPages     = false,
+    pagesDir      = 'pages',
+  } = opts;
+
+  // Will be set in configResolved
+  let _root     = process.cwd();
+  let _pagesAbs = '';
+  let _ws       = null; // Vite WebSocket server (set in configureServer)
+  // Map from absolute page file path → chunk name (e.g. 'route-about')
+  const _routeChunks = new Map();
+
+  return {
+    name: '@ozsarman/clarityjs',
+    enforce: 'pre', // run before other transforms
+
+    // ── Config: inject manualChunks for pages/ ────────────────────────────────
+    config(config, { command }) {
+      if (!codeSplitting || command !== 'build') return;
+
+      const root    = config.root ?? process.cwd();
+      const pgDir   = resolve(root, pagesDir);
+      if (!existsSync(pgDir)) return;
+
+      // Pre-scan pages directory to build chunk map
+      const pageFiles = _scanPageFiles(pgDir);
+      for (const file of pageFiles) {
+        const rel       = relative(pgDir, file).replace(/\\/g, '/').replace(/\.(js|mjs|clarity)$/, '');
+        const chunkName = 'route-' + rel.replace(/\//g, '-').replace(/[\[\]]/g, '').replace(/^-+|-+$/g, '') || 'route-index';
+        _routeChunks.set(file, chunkName);
+      }
+
+      // Inject manualChunks — merges with any user-provided value
+      config.build ??= {};
+      config.build.rollupOptions ??= {};
+      config.build.rollupOptions.output ??= {};
+
+      const userManual = config.build.rollupOptions.output.manualChunks;
+      config.build.rollupOptions.output.manualChunks = (id) => {
+        // Respect user override first
+        if (typeof userManual === 'function') {
+          const u = userManual(id);
+          if (u) return u;
+        }
+        // Our route chunks
+        const chunkName = _routeChunks.get(id);
+        if (chunkName) return chunkName;
+        return null;
+      };
+    },
+
+    // ── ConfigResolved: capture final root ───────────────────────────────────
+    configResolved(config) {
+      _root     = config.root;
+      _pagesAbs = resolve(_root, pagesDir);
+    },
+
+    // ── ConfigureServer: capture WS + watch pages/ for add/remove ────────────
+    configureServer(server) {
+      _ws = server.ws;
+      if (!scanPages) return;
+
+      // When a page file is added or removed, the route table changes, so the
+      // virtual module must be regenerated. Editing a page's contents is handled
+      // by normal .clarity HMR and does not need invalidation here.
+      const invalidatePages = (file) => {
+        if (!file.startsWith(_pagesAbs)) return;
+        const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_PAGES);
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod);
+          server.ws.send({ type: 'full-reload', path: '*' });
+          if (verbose) console.log('[clarity] pages changed → route table reloaded');
+        }
+      };
+      server.watcher.on('add',    invalidatePages);
+      server.watcher.on('unlink', invalidatePages);
+      server.watcher.on('addDir', invalidatePages);
+      server.watcher.on('unlinkDir', invalidatePages);
+    },
+
+    // ── Resolve + load the virtual pages module ──────────────────────────────
+    resolveId(id) {
+      if (scanPages && id === VIRTUAL_PAGES_ID) return RESOLVED_VIRTUAL_PAGES;
+      return null;
+    },
+
+    load(id) {
+      if (scanPages && id === RESOLVED_VIRTUAL_PAGES) {
+        return _generatePagesModule(_pagesAbs, pagesRouterPath);
+      }
+      return null;
+    },
+
+    // ── Transform .clarity files ──────────────────────────────────────────────
+    transform(rawSource, id) {
+      if (!id.endsWith('.clarity')) return null;
+
+      const t0 = Date.now();
+
+      // Is this a dev server build? Vite sets this.environment.mode
+      const isDev = this.environment?.mode !== 'production';
+
+      // ── 1. Extract <style scoped>, <style module>, and <style> blocks ───────
+      const { scoped, global: globalCSS, module: moduleCSS, scopeId, source } = extractStyles(rawSource, id);
+
+      let result;
+      try {
+        result = compile(source, {
+          filename:    id,
+          runtimePath,
+          routerPath,
+          sourceMap:   isDev,
+          types,
+          scopeId,   // passed to CodeGenerator so root element gets data-c-{scopeId}
+        });
+      } catch (err) {
+        // Broadcast rich error to the Clarity error overlay (dev only)
+        if (_ws) {
+          _ws.send({
+            type: 'custom',
+            event: 'clarity:error',
+            data: {
+              type:    'compiler',
+              message: err.message,
+              file:    id,
+              line:    err.line,
+              col:     err.col,
+              frame:   err.frame ?? null,
+              plugin:  '@ozsarman/clarityjs',
+            },
+          });
+        }
+        // Also surface as a Vite build error (shows in terminal + Vite overlay)
+        this.error({
+          message: err.message,
+          id,
+          loc: err.line ? { line: err.line, column: err.col ?? 0 } : undefined,
+        });
+        return null;
+      }
+
+      if (verbose) {
+        console.log(`[clarity] compiled ${id.split('/').pop()} in ${Date.now() - t0}ms`);
+      }
+
+      // ── 2. Inject scope attribute onto root element if scoped CSS exists ──
+      let code = scoped.trim() ? injectScopeAttr(result.code, scopeId) : result.code;
+
+      // ── 2b. CSS Modules — process <style module> and export classMap ──────
+      let moduleCSSTransformed = '';
+      let classMap = {};
+      if (moduleCSS.trim()) {
+        const modResult = cssModules(moduleCSS, scopeId);
+        moduleCSSTransformed = modResult.css;
+        classMap = modResult.classMap;
+        // Export the class map as a named export `styles`
+        code += `\nexport const styles = ${JSON.stringify(classMap)};\n`;
+      }
+
+      // ── 3. Append scoped + module + global CSS as an injected <style> tag ──
+      //       In production builds, the CSS is collected and emitted as a file.
+      if (scoped.trim() || globalCSS.trim() || moduleCSSTransformed) {
+        const css = [
+          globalCSS.trim(),
+          scopeCSS(scoped, scopeId),
+          moduleCSSTransformed,
+        ].filter(Boolean).join('\n');
+
+        if (isDev) {
+          // Inject into <head> at runtime via a JS snippet
+          const escaped = css.replace(/`/g, '\\`').replace(/\$/g, '\\$');
+          code += `\n// <style> injection (Clarity dev)\n` +
+            `(function(){` +
+            `  const _s = document.createElement('style');` +
+            `  _s.setAttribute('data-clarity-style', '${scopeId}');` +
+            `  _s.textContent = \`${escaped}\`;` +
+            `  document.head.appendChild(_s);` +
+            `})();\n`;
+        } else {
+          // In production, store for generateBundle to collect into one CSS file
+          result._clarityCSS = css;
+        }
+      }
+
+      // In dev mode, append the HMR client runtime so Vite can hot-swap modules
+      if (isDev && hmr) {
+        code += HMR_CLIENT_RUNTIME;
+      }
+
+      return {
+        code,
+        map:          result.map ?? null,
+        _clarityDts:  result.dts,
+        _clarityCSS:  result._clarityCSS,
+      };
+    },
+
+    // ── Generate .d.ts + route manifest (build only) ─────────────────────────
+    generateBundle(options, bundle) {
+      // ── TypeScript declarations ─────────────────────────────────────────────
+      if (types) {
+        for (const [fileName, chunk] of Object.entries(bundle)) {
+          if (chunk.type !== 'chunk' || !chunk.facadeModuleId?.endsWith('.clarity')) continue;
+          const dts = chunk._clarityDts;
+          if (dts) {
+            this.emitFile({
+              type:     'asset',
+              fileName: fileName.replace(/\.js$/, '.d.ts'),
+              source:   dts,
+            });
+          }
+        }
+      }
+
+      // ── Route manifest for modulepreload + prefetch ─────────────────────────
+      if (codeSplitting) {
+        const manifest = {};
+        for (const [fileName, chunk] of Object.entries(bundle)) {
+          if (chunk.type !== 'chunk') continue;
+          const facadeId = chunk.facadeModuleId ?? '';
+          if (!facadeId) continue;
+
+          const chunkName = _routeChunks.get(facadeId);
+          if (!chunkName) continue;
+
+          // Derive route path from chunkName: 'route-users-id' → '/users/:id'
+          const routePath = '/' + chunkName
+            .replace(/^route-/, '')
+            .replace(/-/g, '/')
+            .replace(/index$/, '')
+            .replace(/\/+$/, '') || '/';
+
+          manifest[routePath] = {
+            chunk:   fileName,
+            imports: chunk.imports ?? [],
+          };
+        }
+
+        this.emitFile({
+          type:     'asset',
+          fileName: 'clarity-route-manifest.json',
+          source:   JSON.stringify(manifest, null, 2),
+        });
+      }
+    },
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Recursively collect all page files from a directory */
+function _scanPageFiles(dir, files = []) {
+  if (!existsSync(dir)) return files;
+  for (const entry of readdirSync(dir)) {
+    if (entry.startsWith('_')) continue; // skip _layout.js etc.
+    const full = join(dir, entry);
+    const info = statSync(full);
+    if (info.isDirectory()) {
+      _scanPageFiles(full, files);
+    } else if (/\.(js|mjs|clarity)$/.test(entry)) {
+      files.push(full);
+    }
+  }
+  return files;
+}