@oddsquad/vite-plugin-lit 0.3.0 → 0.5.0

package/lib/plugin.js

@@ -3,490 +3,27 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: BSD-3-Clause
  */
-import {existsSync} from 'node:fs';
-import {resolve as resolvePath, sep} from 'node:path';
-import {fileURLToPath} from 'node:url';
+import {resolve as resolvePath} from 'node:path';
 import {loadEnv} from 'vite';
 import MagicString from 'magic-string';
-import {isTrustedRequest} from './http.js';
 import {injectSourceMeta} from './source-meta.js';
 import {INSTALL_ID, VIRTUAL_PREFIX, transformLitModule} from './transform.js';
 import {WRAP_TABLE} from './wrap-table.js';
 import {createLitDevframePlugin} from './devframe/vite.js';
 import {PACKAGE_VERSION} from './devframe/paths.js';
-const CSS_SHEET_BUILD_MODES = ['auto', 'url', 'inline', 'inline-raw'];
-/** Env var prefix consumed at config time. */
-const ENV_PREFIX = 'LIT_PLUGIN';
-/** Parse a boolean-ish env string; `undefined` when unset/unrecognized. */
-const envBool = (v) =>
-  v === 'true' || v === '1'
-    ? true
-    : v === 'false' || v === '0'
-      ? false
-      : undefined;
-/** Parse a numeric env string; `undefined` when unset/non-numeric. */
-const envNum = (v) => {
-  if (v === undefined || v === '') return undefined;
-  const n = Number(v);
-  return Number.isNaN(n) ? undefined : n;
-};
-/**
- * Parse a string against a closed set of values; `undefined` (with a warning)
- * when set to something outside it, so a typo falls back to the default
- * instead of silently disabling a feature.
- */
-const envEnum = (v, allowed, source) => {
-  if (v === undefined || v === '') return undefined;
-  if (allowed.includes(v)) return v;
-  console.warn(
-    `[lit-plugin] ignoring ${source}=${JSON.stringify(v)}; expected one of ` +
-      allowed.map((a) => JSON.stringify(a)).join(', ')
-  );
-  return undefined;
-};
-/**
- * Merge explicit options over env vars over defaults (in that precedence) into
- * the flat shape the plugin hooks consume.
- */
-export const resolveOptions = (options, env) => {
-  const hmr = options.hmr;
-  const hmrObj = typeof hmr === 'object' ? hmr : undefined;
-  const hmrEnabled =
-    (typeof hmr === 'boolean' ? hmr : hmrObj?.enabled) ??
-    envBool(env[`${ENV_PREFIX}_HMR`]) ??
-    true;
-  const reconnect =
-    hmrObj?.reconnect ?? envBool(env[`${ENV_PREFIX}_HMR_RECONNECT`]) ?? false;
-  const onIncompatible =
-    hmrObj?.onIncompatible ??
-    env[`${ENV_PREFIX}_HMR_ON_INCOMPATIBLE`] ??
-    'reload';
-  const ind = hmrObj?.indicator;
-  const indObj = typeof ind === 'object' ? ind : undefined;
-  const indEnabled =
-    (typeof ind === 'boolean' ? ind : indObj?.enabled) ??
-    envBool(env[`${ENV_PREFIX}_HMR_INDICATOR`]) ??
-    true;
-  const indCount =
-    indObj?.count ?? envBool(env[`${ENV_PREFIX}_HMR_INDICATOR_COUNT`]) ?? false;
-  // The indicator is meaningless without HMR, so it follows the master toggle.
-  const indicator = hmrEnabled && indEnabled ? {count: indCount} : false;
-  const so = options.sourceOverlay;
-  const soExplicit =
-    typeof so === 'boolean' ? so : so === undefined ? undefined : true;
-  const soEnabled =
-    soExplicit ?? envBool(env[`${ENV_PREFIX}_SOURCE_OVERLAY`]) ?? false;
-  let sourceOverlay = false;
-  if (soEnabled) {
-    const base = typeof so === 'object' ? {...so} : {};
-    base.key ??= env[`${ENV_PREFIX}_SOURCE_OVERLAY_KEY`] || undefined;
-    base.editor ??= env[`${ENV_PREFIX}_SOURCE_OVERLAY_EDITOR`] || undefined;
-    base.throttleMs ??= envNum(env[`${ENV_PREFIX}_SOURCE_OVERLAY_THROTTLE_MS`]);
-    sourceOverlay = base;
-  }
-  const timeline =
-    options.timeline ?? envBool(env[`${ENV_PREFIX}_TIMELINE`]) ?? false;
-  const cssSheetBuild =
-    envEnum(options.cssSheetBuild, CSS_SHEET_BUILD_MODES, 'cssSheetBuild') ??
-    envEnum(
-      env[`${ENV_PREFIX}_CSS_SHEET_BUILD`],
-      CSS_SHEET_BUILD_MODES,
-      `${ENV_PREFIX}_CSS_SHEET_BUILD`
-    ) ??
-    'auto';
-  return {
-    hmrEnabled,
-    reconnect,
-    onIncompatible,
-    indicator,
-    sourceOverlay,
-    timeline,
-    cssSheetBuild,
-  };
-};
-/**
- * Flattens resolved options into the JSON-serializable shape the panel's
- * Settings tab consumes (callback options like `exclude`/`onSelect` dropped;
- * a custom editor object reported as `"custom"`). Default key/editor/throttle
- * are applied here so the panel shows the effective values the runtime uses.
- */
-const toFeatureSettings = (r) => {
-  const so = r.sourceOverlay;
-  const editor = so === false ? undefined : so.editor;
-  return {
-    hmr: {
-      enabled: r.hmrEnabled,
-      reconnect: r.reconnect,
-      onIncompatible: r.onIncompatible,
-      indicatorEnabled: r.indicator !== false,
-      indicatorCount: r.indicator !== false && r.indicator.count,
-    },
-    sourceOverlay: {
-      enabled: so !== false,
-      key: (so === false ? undefined : so.key) ?? 's',
-      editor:
-        typeof editor === 'string' ? editor : editor ? 'custom' : 'vscode',
-      throttleMs: (so === false ? undefined : so.throttleMs) ?? 50,
-    },
-    timeline: r.timeline,
-  };
-};
-/**
- * Resolves a runtime module to an absolute fs path (served via `/@fs/`), so
- * the plugin works from any served root. Falls back from the built `.js` to
- * the `.ts` source when running un-built (e.g. under vitest).
- */
-const resolveRuntimeModule = (name) => {
-  for (const ext of ['js', 'ts']) {
-    const url = new URL(`./runtime/${name}.${ext}`, import.meta.url);
-    if (existsSync(url)) {
-      return fileURLToPath(url).replace(/\\/g, '/');
-    }
-  }
-  throw new Error(`[lit-plugin] runtime module not found: ${name}`);
-};
-const JS_FILE_RE = /\.[cm]?[jt]sx?$/;
-const OPEN_IN_EDITOR_PATH = '/__lit-open-in-editor';
-export const createOpenInEditorMiddleware = (allowedRoots) => {
-  // First entry is the primary root: relative `file` params resolve against
-  // it. Every entry grants open access to files beneath it.
-  const roots = allowedRoots.map((r) => resolvePath(r));
-  return (req, res, next) => {
-    if (req.url === undefined) {
-      next();
-      return;
-    }
-    if (req.method !== undefined && req.method !== 'GET') {
-      res.statusCode = 405;
-      res.end('method not allowed');
-      return;
-    }
-    if (!isTrustedRequest(req.headers ?? {})) {
-      res.statusCode = 403;
-      res.end('forbidden');
-      return;
-    }
-    const query = req.url.includes('?')
-      ? req.url.slice(req.url.indexOf('?') + 1)
-      : '';
-    const params = new URLSearchParams(query);
-    const file = params.get('file');
-    if (file === null) {
-      res.statusCode = 400;
-      res.end('missing file parameter');
-      return;
-    }
-    // Confine the open to the allowed roots: resolve the requested path and
-    // reject anything that escapes all of them (path traversal, absolute
-    // paths to arbitrary files). `launch-editor` spawns the user's editor on
-    // this path, so an unvalidated `file` is a local-file-open /
-    // arg-injection vector.
-    const resolved = resolvePath(roots[0] ?? process.cwd(), file);
-    const allowed = roots.some(
-      (root) => resolved === root || resolved.startsWith(root + sep)
-    );
-    if (!allowed) {
-      res.statusCode = 403;
-      res.end('file outside allowed roots');
-      return;
-    }
-    if (!existsSync(resolved)) {
-      res.statusCode = 404;
-      res.end('file not found');
-      return;
-    }
-    // Coerce to integers so a crafted `line`/`column` can't smuggle extra
-    // shell-visible content through the `file:line:column` ref.
-    const line = String(
-      Math.max(1, Number.parseInt(params.get('line') ?? '1', 10) || 1)
-    );
-    const column = String(
-      Math.max(1, Number.parseInt(params.get('column') ?? '1', 10) || 1)
-    );
-    const fileRef = `${resolved}:${line}:${column}`;
-    import('launch-editor')
-      .then((mod) => {
-        const launch = mod.default ?? mod;
-        // `launch-editor` invokes the callback only on failure — synchronously
-        // when it can't guess an editor, later if the spawn errors. Reply `ok`
-        // right after launching; the guard keeps a sync failure's 500 first
-        // and drops a late async failure (the response is long gone).
-        let finished = false;
-        const finish = (statusCode, msg) => {
-          if (finished) return;
-          finished = true;
-          res.statusCode = statusCode;
-          res.end(msg);
-        };
-        launch(fileRef, (_fileName, errorMessage) => {
-          if (errorMessage !== null) {
-            finish(500, errorMessage);
-          }
-        });
-        finish(200, 'ok');
-      })
-      .catch(next);
-  };
-};
-/**
- * `import href from './x.css?hmr-url'` — `?url` semantics with working HMR.
- * The string is a real stylesheet URL (dev-served CSS file; hashed `.css`
- * asset on build) for shadow-root `<link>` hrefs and `@import url()`s. In
- * dev, each HMR re-execution yields a freshly cache-busted href, so the
- * browser refetches the changed stylesheet; in build the `?url` asset URL
- * passes through unchanged.
- */
-const CSS_URL_QUERY_RE = /^([^?]+\.css)\?(?:[^&]*&)*hmr-url(?:&.*)?$/;
-const CSS_URL_VIRTUAL_PREFIX = '\0lit-plugin:hmr-url:';
-/**
- * `import sheet from './x.css?css-sheet'` — a constructed, shareable
- * `CSSStyleSheet` backed by the `.css` asset that hot-swaps in place. Adopt it
- * from any number of components (`static styles = [sheet]`); a source edit
- * re-fetches and `replaceSync()`s it, updating every shadow root that adopted
- * it without re-rendering a component or reloading the page.
- *
- * This is the `urlSheet()` helper plus its irreducible HMR wiring, lifted into
- * a plugin-generated module: the `import.meta.hot.accept` lives here (where
- * Vite's static analysis sees the literal specifier), so callers write a bare
- * import and never touch `import.meta.hot` themselves.
- *
- * Under `vite build` the generated module can instead inline the css text (see
- * `cssSheetBuild`) — a library's consumers bundle its JS only, so a
- * fetch-backed sheet would 404 on the `.css` asset that never reached their
- * build.
- */
-const CSS_SHEET_QUERY_RE = /^([^?]+\.css)\?(?:[^&]*&)*css-sheet(?:&.*)?$/;
-const CSS_SHEET_VIRTUAL_PREFIX = '\0lit-plugin:css-sheet:';
-// The virtual id must not end in `.css`, or Vite's CSS plugins (which match
-// the id's extension regardless of `\0`) would compile the wrapper as CSS.
-const CSS_VIRTUAL_SUFFIX = '.js';
-/**
- * Import-query support, served in dev and build alike (source code using
- * `?hmr-url`/`?css-sheet` must keep working under `vite build`, where the HMR
- * plugin doesn't apply). Exported for the baseline e2e run, which needs the
- * queries working without the HMR plugin.
- *
- * `getCssSheetBuild` is a getter, not a value: `litPlugin()` re-resolves its
- * options against the loaded env in a `config` hook, which runs after the
- * plugin array is built. Standalone (no getter) it behaves like the `'auto'`
- * default.
- */
-export const litCssQueries = (getCssSheetBuild = () => 'auto') => {
-  let isBuild = false;
-  let isLib = false;
-  return {
-    name: 'lit-css-query',
-    // Vite's core resolver claims `./x.css?hmr-url` for the CSS pipeline
-    // before normal plugins get a look, so resolve ahead of it.
-    enforce: 'pre',
-    configResolved(config) {
-      isBuild = config.command === 'build';
-      isLib = config.build.lib !== false && config.build.lib !== undefined;
-    },
-    async resolveId(id, importer) {
-      const prefix = CSS_URL_QUERY_RE.test(id)
-        ? CSS_URL_VIRTUAL_PREFIX
-        : CSS_SHEET_QUERY_RE.test(id)
-          ? CSS_SHEET_VIRTUAL_PREFIX
-          : null;
-      if (prefix === null) {
-        return null;
-      }
-      const file = id.slice(0, id.indexOf('?'));
-      const resolved = await this.resolve(file, importer);
-      if (resolved === null) {
-        return null;
-      }
-      return prefix + resolved.id + CSS_VIRTUAL_SUFFIX;
-    },
-    load(id) {
-      const helperPath = resolveRuntimeModule('css');
-      if (id.startsWith(CSS_URL_VIRTUAL_PREFIX)) {
-        const file = id.slice(
-          CSS_URL_VIRTUAL_PREFIX.length,
-          -CSS_VIRTUAL_SUFFIX.length
-        );
-        return {
-          code:
-            `import url from ${JSON.stringify(`${file}?url`)};\n` +
-            `import {devCacheBust} from ${JSON.stringify(helperPath)};\n` +
-            `export default devCacheBust(url);\n`,
-          moduleType: 'js',
-        };
-      }
-      if (id.startsWith(CSS_SHEET_VIRTUAL_PREFIX)) {
-        const file = id.slice(
-          CSS_SHEET_VIRTUAL_PREFIX.length,
-          -CSS_VIRTUAL_SUFFIX.length
-        );
-        const mode = getCssSheetBuild();
-        const inlineQuery =
-          !isBuild || mode === 'url' || (mode === 'auto' && !isLib)
-            ? null
-            : mode === 'inline-raw'
-              ? '?raw'
-              : '?inline';
-        if (inlineQuery !== null) {
-          // Build only, so no `import.meta.hot` block. The sheet is still
-          // constructed once per virtual module, so adopters share it exactly
-          // as they do in the fetch-backed form.
-          return {
-            code:
-              `import css from ${JSON.stringify(`${file}${inlineQuery}`)};\n` +
-              `const sheet = new CSSStyleSheet();\n` +
-              `sheet.replaceSync(css);\n` +
-              `export default sheet;\n`,
-            moduleType: 'js',
-          };
-        }
-        // The accept specifier must be byte-identical to the import above —
-        // Vite resolves accepted HMR deps by static analysis. Generating both
-        // here is exactly what frees the caller from writing it. The swap is
-        // self-accepted at this boundary, so it never propagates to adopters.
-        const urlSpecifier = JSON.stringify(`${file}?url`);
-        return {
-          code:
-            `import url from ${urlSpecifier};\n` +
-            `import {urlSheet} from ${JSON.stringify(helperPath)};\n` +
-            `const {sheet, onHotUpdate} = urlSheet(url);\n` +
-            `export default sheet;\n` +
-            `if (import.meta.hot) {\n` +
-            `  import.meta.hot.accept(${urlSpecifier}, onHotUpdate);\n` +
-            `}\n`,
-          moduleType: 'js',
-        };
-      }
-      return null;
-    },
-  };
-};
-const TIMELINE_VIRTUAL_ID = 'virtual:lit-plugin/timeline';
-const TIMELINE_RESOLVED_ID = '\0virtual:lit-plugin/timeline';
-const TIMELINE_STUB =
-  'export const addTimelineEvent = () => {};\n' +
-  'export const addTimelineLayer = () => {};\n';
-/**
- * The public timeline API virtual module, served in dev and build alike:
- * app code importing it must keep building under `vite build`, where the HMR
- * plugin doesn't apply. While these hooks lived on that serve-only plugin,
- * nothing claimed the specifier during a build and the bundler failed to
- * resolve it.
- *
- * `getTimeline` is a getter, not a value: `litPlugin()` re-resolves its
- * options against the loaded env in a `config` hook, which runs after the
- * plugin array is built.
- */
-export const litTimelineVirtual = (getTimeline = () => false) => {
-  let isBuild = false;
-  return {
-    name: 'lit-timeline-virtual',
-    configResolved(config) {
-      isBuild = config.command === 'build';
-    },
-    resolveId(id) {
-      return id === TIMELINE_VIRTUAL_ID ? TIMELINE_RESOLVED_ID : null;
-    },
-    load(id) {
-      if (id !== TIMELINE_RESOLVED_ID) {
-        return null;
-      }
-      // Under build the stub is unconditional, even with `timeline: true`.
-      // The runtime delivers only over `import.meta.hot`, so in a production
-      // bundle it is a queue that never drains; the stub keeps the transport
-      // out of the bundle and makes the documented "no-op in production"
-      // behavior true.
-      if (isBuild || !getTimeline()) {
-        return {code: TIMELINE_STUB, moduleType: 'js'};
-      }
-      const apiPath = resolveRuntimeModule('timeline/public-api');
-      return {
-        code: `export * from ${JSON.stringify(apiPath)};\n`,
-        moduleType: 'js',
-      };
-    },
-  };
-};
-/**
- * A `css` tagged template literal with no interpolations and no escape
- * sequences — the only kind we can hand to a CSS parser as-is. Literals
- * with `${…}` holes or backslashes simply don't match and stay untouched.
- * The lookbehind keeps `unsafeCSS`/`myCss`-style tags from matching.
- */
-const CSS_LITERAL_RE = /(?<![\w$.])css`((?:[^`\\$]|\$(?!\{))*)`/g;
-/**
- * Runs Vite's configured Lightning CSS over `css` tagged template literals
- * in user modules, which the CSS pipeline itself never sees (they're plain
- * JS strings to it). Inert unless `css.transformer` is `'lightningcss'`;
- * options come from `css.lightningcss`, so component styles get the same
- * treatment (targets, drafts, …) as `.css` files. Applies in dev and build.
- */
-const litCssLiterals = () => {
-  let lightningcss = null;
-  let options;
-  let minify = false;
-  return {
-    name: 'lit-css-literals',
-    async configResolved(config) {
-      if (config.css.transformer !== 'lightningcss') {
-        return;
-      }
-      // The transformer setting guarantees the dependency: Vite itself
-      // can't process .css files without it.
-      lightningcss = await import('lightningcss');
-      // cssModules makes no sense for a literal; everything else carries
-      // over.
-      const {cssModules: _cssModules, ...rest} = config.css.lightningcss ?? {};
-      options = rest;
-      minify = config.command === 'build';
-    },
-    transform(code, id) {
-      if (lightningcss === null) {
-        return null;
-      }
-      if (id.startsWith('\0') || id.includes('/node_modules/')) {
-        return null;
-      }
-      const [file] = id.split('?', 2);
-      if (!JS_FILE_RE.test(file) || !code.includes('css`')) {
-        return null;
-      }
-      const ms = new MagicString(code);
-      let changed = false;
-      for (const m of code.matchAll(CSS_LITERAL_RE)) {
-        const literal = m[1];
-        if (literal.trim() === '') {
-          continue;
-        }
-        let out;
-        try {
-          const result = lightningcss.transform({
-            ...options,
-            filename: file,
-            code: Buffer.from(literal),
-            minify,
-          });
-          out = Buffer.from(result.code).toString();
-        } catch (e) {
-          this.warn(
-            `[lit-plugin] skipping css literal Lightning CSS couldn't parse: ${e.message}`
-          );
-          continue;
-        }
-        // Re-escape for the template literal the output goes back into.
-        out = out.replace(/[\\`$]/g, '\\$&');
-        if (out !== literal) {
-          const start = m.index + 'css`'.length;
-          ms.overwrite(start, start + literal.length, out);
-          changed = true;
-        }
-      }
-      if (!changed) {
-        return null;
-      }
-      return {code: ms.toString(), map: ms.generateMap({hires: true})};
-    },
-  };
-};
+import {ENV_PREFIX, resolveOptions, toFeatureSettings} from './options.js';
+import {
+  OPEN_IN_EDITOR_PATH,
+  createOpenInEditorMiddleware,
+} from './plugins/open-in-editor.js';
+import {litCssQueries} from './plugins/css-queries.js';
+import {litTimelineVirtual} from './plugins/timeline-virtual.js';
+import {litCssLiterals} from './plugins/css-literals.js';
+import {resolveRuntimeModule, JS_FILE_RE} from './plugins/shared.js';
+export {createOpenInEditorMiddleware} from './plugins/open-in-editor.js';
+export {litCssQueries} from './plugins/css-queries.js';
+export {litTimelineVirtual} from './plugins/timeline-virtual.js';
+export {resolveOptions} from './options.js';
 /**
  * Vite plugin set providing HMR, CSS helpers, and Lightning CSS processing
  * for Lit projects.
@@ -748,6 +285,14 @@ export const litPlugin = (options = {}) => {
       createLitDevframePlugin({
         version: PACKAGE_VERSION,
         features: () => toFeatureSettings(resolved),
+        // Only a named editor counts: `toFeatureSettings` reports `vscode`
+        // for "never chose", which must not turn into a forced `code`.
+        configuredEditor: () => {
+          const so = resolved.sourceOverlay;
+          return so !== false && typeof so.editor === 'string'
+            ? so.editor
+            : undefined;
+        },
       })
     );
   }