@statewalker/webrun-modules 0.1.0

package/src/transform/transform-cjs.ts

@@ -0,0 +1,85 @@
+import { init, parse } from "cjs-module-lexer";
+import type { SourceFile, Transform } from "../types.js";
+
+let lexerReady: Promise<unknown> | undefined;
+
+// Matches `require("x")` / `require('x')` with a static string literal argument.
+const REQUIRE_RE = /require\(\s*(['"])((?:(?!\1)[^\\]|\\.)*)\1\s*\)/g;
+
+const IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/** Collect the unique static-string `require(...)` specifiers in a CJS source. */
+function findRequires(source: string): string[] {
+  const set = new Set<string>();
+  for (const m of source.matchAll(REQUIRE_RE)) set.add(m[2]);
+  return [...set];
+}
+
+/**
+ * Transform a CommonJS file into served, browser-runnable ESM — no global runtime
+ * registry: each static `require` target is a static namespace import, so the ESM
+ * module graph itself provides load ordering and circular-dep handling. The CJS
+ * body runs synchronously against a synthetic `require` that maps specifiers to
+ * those namespaces; named exports (via `cjs-module-lexer`) are re-exported as
+ * eval-time snapshots (valid because the body executed synchronously above).
+ * Computed `require(expr)` hits the synthetic require's miss path (throws) — the
+ * declared `esbuild-wasm` fallback's job.
+ */
+export function newCjsTransform(): Transform {
+  return {
+    async transform(file: SourceFile, rewrite: (specifier: string) => string): Promise<string> {
+      lexerReady ??= init();
+      await lexerReady;
+
+      const specs = findRequires(file.source);
+      const importLines: string[] = [];
+      const mapEntries: string[] = [];
+      specs.forEach((spec, i) => {
+        importLines.push(`import * as __d${i} from ${JSON.stringify(rewrite(spec))};`);
+        mapEntries.push(`  ${JSON.stringify(spec)}: __d${i},`);
+      });
+
+      let names: string[] = [];
+      let reexports: string[] = [];
+      try {
+        const parsed = parse(file.source);
+        names = parsed.exports.filter((n) => IDENT_RE.test(n) && n !== "default");
+        reexports = parsed.reexports;
+      } catch {
+        names = []; // lexer can't parse → default-only interop
+      }
+      const namedExports = [...new Set(names)]
+        .map((n) => `export const ${n} = module.exports.${n};`)
+        .join("\n");
+      // A `module.exports = require("x")` entry (e.g. React's `index.js`) has no
+      // own statically-lexable names — only a reexport. Surface x's named exports
+      // by re-exporting its already-served namespace, so `import { StrictMode }
+      // from "react"` (and the automatic-JSX `jsxDEV` import) resolve. `export *`
+      // never re-exports `default`, so the `export default module.exports` above
+      // stays authoritative.
+      const reexportLines = [...new Set(reexports)]
+        .map((spec) => `export * from ${JSON.stringify(rewrite(spec))};`)
+        .join("\n");
+
+      const dir = file.path.replace(/\/[^/]*$/, "");
+      return [
+        ...importLines,
+        `const __ns = {\n${mapEntries.join("\n")}\n};`,
+        `const module = { exports: {} };`,
+        `const require = (s) => {`,
+        `  const m = __ns[s];`,
+        `  if (!m) throw new Error("Cannot require (computed/unresolved): " + s);`,
+        `  return m.default !== undefined ? m.default : m;`,
+        `};`,
+        `(function (module, exports, require, __filename, __dirname) {`,
+        file.source,
+        `}).call(module.exports, module, module.exports, require, ${JSON.stringify(file.path)}, ${JSON.stringify(dir)});`,
+        `export default module.exports;`,
+        namedExports,
+        reexportLines,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    },
+  };
+}

package/src/transform/transform-esm.ts

@@ -0,0 +1,35 @@
+import { init, parse } from "es-module-lexer";
+import type { SourceFile, Transform } from "../types.js";
+import { toJs } from "./to-js.js";
+
+let lexerReady: Promise<unknown> | undefined;
+
+/**
+ * The default per-file transform for ESM (and TS/JSX) sources: transpile to plain
+ * JS, then rewrite every static/dynamic-string import & re-export specifier in
+ * place via `rewrite`, leaving quotes and everything else byte-for-byte intact.
+ * Computed dynamic specifiers (no static string) are left untouched.
+ */
+export function newEsmTransform(): Transform {
+  return {
+    async transform(file: SourceFile, rewrite: (specifier: string) => string): Promise<string> {
+      lexerReady ??= init;
+      await lexerReady;
+      const js = toJs(file.source, file.format, file.path);
+      const [imports] = parse(js, file.path);
+      let out = js;
+      // Splice from the end so earlier offsets stay valid. For static imports the
+      // [s,e) span sits *inside* the quotes; for dynamic `import("x")` it *includes*
+      // them — detect a leading quote and preserve it either way.
+      for (let i = imports.length - 1; i >= 0; i--) {
+        const imp = imports[i];
+        if (imp.n == null) continue; // computed/dynamic specifier — cannot rewrite statically
+        const q = out[imp.s];
+        const quoted = q === '"' || q === "'" || q === "`";
+        const replacement = quoted ? q + rewrite(imp.n) + q : rewrite(imp.n);
+        out = out.slice(0, imp.s) + replacement + out.slice(imp.e);
+      }
+      return out;
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,143 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+
+/**
+ * Public contract for `@statewalker/webrun-modules`. Types only — the resolver
+ * core, the default npm `Source`, and the transforms are implemented separately.
+ * Contract source: notes/2026/2026-07/2026-07-23/grill-module-webrun-modules.md
+ */
+
+/** The build target — selects `exports` conditions and is part of the cache key. */
+export type ModuleTarget = "browser" | "node";
+
+/**
+ * A reference to resolve: either an npm package (with optional pinned version and
+ * subpath) or a URL (a local project script served by this server, or an already
+ * resolved local URL).
+ */
+export type ModuleRef = { pkg: string; version?: string; subpath?: string } | { url: string };
+
+/** The result of resolving a `ModuleRef`: a directly `import`-able local URL. */
+export interface ResolvedModule {
+  /** Importable URL — `/{name}@{version}/{subpath}` for a package, carries `basePath`. */
+  url: string;
+  target: ModuleTarget;
+}
+
+/**
+ * The version-dedupe map produced by `prime` and reusable as a pin input. One
+ * artifact, two roles: a partial lockfile pins only the names it lists; `prime`
+ * writes the complete one back to the cache.
+ */
+export type Lockfile = Record<string, string /* resolved version */>;
+
+/** A parsed `package.json` (only the fields resolution reads). */
+export interface PackageManifest {
+  name: string;
+  version: string;
+  main?: string;
+  module?: string;
+  browser?: string | Record<string, string | false>;
+  exports?: unknown;
+  imports?: unknown;
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+/** A package acquired by a `Source`: its untarred files plus parsed manifest. */
+export interface LoadedPackage {
+  name: string;
+  version: string;
+  /** The untarred package tree — every file individually addressable. */
+  files: FilesApi;
+  manifest: PackageManifest;
+}
+
+/**
+ * Pluggable acquisition seam. The default impl fetches an npm registry tarball and
+ * untars it in memory; JSR and direct-URL are alternative impls.
+ */
+export interface Source {
+  /** Whether this source handles the given reference (npm | jsr | url). */
+  matches(ref: ModuleRef): boolean;
+  /** Resolve a concrete version, fetch bytes, untar, parse the manifest. */
+  load(ref: ModuleRef): Promise<LoadedPackage>;
+}
+
+/** The source-file kinds the transform distinguishes. */
+export type SourceFormat = "esm" | "cjs" | "ts" | "tsx";
+
+export interface SourceFile {
+  path: string;
+  source: string;
+  format: SourceFormat;
+}
+
+/**
+ * Pluggable per-file transform seam. Turns one raw file into browser-runnable ESM,
+ * passing every discovered specifier through `rewrite` (which returns the
+ * same-origin, prefix-portable relative URL to emit).
+ */
+export interface Transform {
+  transform(file: SourceFile, rewrite: (specifier: string) => string): Promise<string>;
+}
+
+export interface ModuleServerOptions {
+  /** Injected cache — NodeFilesApi / browser-OPFS / MemFilesApi. Never node:fs. */
+  cache: FilesApi;
+  /** Optional: local project files served under their own paths (authored scripts). */
+  project?: FilesApi;
+  /** Acquisition sources; defaults to `[npmRegistrySource()]`. */
+  sources?: Source[];
+  /** Per-file transform; defaults to the sucrase-based ESM + CJS-interop transform. */
+  transform?: Transform;
+  /** Selects `exports` conditions and cache key. Defaults to `"browser"`. */
+  target?: ModuleTarget;
+  /** Optional lockfile input for reproducible resolution; also written by `prime`. */
+  lock?: Lockfile;
+  /** Mount prefix, e.g. `"/deps/v1/"`. Defaults to `"/"`. */
+  basePath?: string;
+  /** Prefix (relative to `basePath`) for external package URLs, isolating npm
+   *  deps under e.g. `"deps/"` while authored project files stay at `~/`.
+   *  Defaults to `""` — packages served alongside project files. */
+  depsPath?: string;
+}
+
+export interface ModuleServer {
+  /** Resolve a single reference to an importable local URL (resolve-on-miss). */
+  resolve(ref: ModuleRef, importer?: string): Promise<ResolvedModule>;
+  /** Walk the entry's whole graph, warm the cache, write `lock`. */
+  prime(entry: ModuleRef): Promise<ResolvedModule>;
+  /** Prime an entry and return every reachable module URL (the exact set of
+   *  scripts required to run it, `basePath`-prefixed, sorted). */
+  listResources(entry: ModuleRef): Promise<string[]>;
+  /** List every file of a package (raw, package-relative paths), loading it if
+   *  needed — the full package contents, not just the reachable subset. */
+  listPackageFiles(ref: ModuleRef): Promise<string[]>;
+  /** Standard Web handler; serves the cache and matches under `basePath`. */
+  fetch(request: Request): Promise<Response>;
+  /** The resolved graph — also the persisted lockfile. */
+  readonly lock: Lockfile;
+}
+
+/** Thrown when a package / version / subpath cannot be resolved. */
+export class ModuleResolveError extends Error {
+  constructor(
+    readonly ref: ModuleRef,
+    readonly reason: string,
+  ) {
+    super(`Cannot resolve ${JSON.stringify(ref)}: ${reason}`);
+    this.name = "ModuleResolveError";
+  }
+}
+
+/** Thrown when a file cannot be transformed to runnable ESM. */
+export class ModuleTransformError extends Error {
+  constructor(
+    readonly path: string,
+    readonly reason: string,
+  ) {
+    super(`Cannot transform ${path}: ${reason}`);
+    this.name = "ModuleTransformError";
+  }
+}