module-tsx 0.0.1 → 0.0.3

package/README.md

@@ -1,31 +1,30 @@
 # module-tsx
 
-Run TypeScript (and React) module directly in the browser.
+Run TypeScript (and React) modules directly in the browser, without a build step.
 
-# Usage
+## Usage
 
 ```html
-<!-- Load This Library -->
+<!-- Load this library -->
 <script type="module" src="https://esm.sh/module-tsx"></script>
 
 <div id="root"></div>
 
-<!-- Write Your TypeScript Module -->
+<!-- Write your TypeScript/TSX inline -->
 <script type="module-tsx">
-  import React from "react"; // <- This will be converted to https://esm.sh/react
-  import { createRoot } from "react-dom/client"; // <- This will also be converted automatically
-  import App from "./src/App.tsx"; // <- Your TypeScript module will also be compiled on the fly
-  import lib from "https://my.cdn.domain"; // <- Direct http import will NOT be compiled
+  import React from "react"; // bare specifier → https://esm.sh/react
+  import { createRoot } from "react-dom/client";
+  import App from "./src/App.tsx"; // relative imports are fetched and compiled on the fly
 
-  const root = document.getElementById("root") as HTMLDivElement; // <- You can write TypeScript directly
+  const root = document.getElementById("root") as HTMLDivElement;
   createRoot(root).render(
     <React.StrictMode>
       <App />
     </React.StrictMode>
-    // ^ You can also write JSX/TSX directly
   );
 </script>
-<!-- OR -->
+
+<!-- OR load an external file -->
 <script type="module-tsx" src="./main.tsx"></script>
 ```
 
@@ -37,3 +36,72 @@ export default function App() {
   return <div>Hello, module-tsx!</div>;
 }
 ```
+
+## Features
+
+- **TypeScript & JSX/TSX** — transpiled on the fly using the TypeScript compiler
+- **Bare specifier resolution** — `import "react"` is automatically rewritten to a CDN URL (defaults to `https://esm.sh/`)
+- **Relative imports** — `.ts`/`.tsx` files are fetched and compiled recursively
+- **CSS imports** — `import "./style.css"` injects a `<style>` tag; `import "./style.module.css"` returns a CSS Modules object
+- **Import map support** — respects `<script type="importmap">` on the page for specifier overrides
+- **Auto React import** — JSX is detected and `import React from "react"` is injected automatically if missing
+
+## Programmatic API
+
+```ts
+import { ModuleTSX } from "module-tsx";
+
+const m = new ModuleTSX({
+  baseUrl: location.href, // base for resolving relative specifiers
+  importMap: { imports: { react: "https://esm.sh/react" } }, // merged with page importmaps
+  resolveBareSpecifier: "https://cdn.jsdelivr.net/npm/", // string prefix or function
+});
+
+// Import a module by specifier
+const react = await m.import("react");
+const app = await m.import("./app.tsx");
+
+// Import from an in-memory string
+const { x } = await m.importCode(
+  document.location.href,
+  `export const x: number = 1`,
+);
+
+// Events
+m.addEventListener("import", (e) => console.log("loading", e.detail.id));
+m.addEventListener("import:error", (e) =>
+  console.error("failed", e.detail.id, e.detail.error),
+);
+m.addEventListener("transform", (e) =>
+  console.log("compiling", e.detail.sourceUrl),
+);
+m.addEventListener("transform:error", (e) =>
+  console.error("compile error", e.detail.sourceUrl, e.detail.error),
+);
+```
+
+## Use with AI
+
+module-tsx is well-suited for AI-generated pages — an AI can produce a single, self-contained HTML file that runs TypeScript and React directly in the browser with no build step or configuration.
+
+To use the skill, run
+
+```sh
+npx skills add yieldray/module-tsx
+```
+
+## CDN
+
+```html
+<!-- ESM -->
+<script type="module" src="https://esm.sh/module-tsx"></script>
+
+<!-- ESM (self-contained, no external dependencies) -->
+<script
+  type="module"
+  src="https://raw.esm.sh/module-tsx/dist/index.mjs"
+></script>
+
+<!-- UMD (exposes window.ModuleTSX) -->
+<script src="https://raw.esm.sh/module-tsx/dist/index.umd.js"></script>
+```

package/dist/index.d.ts

@@ -1,7 +1,28 @@
 //#region src/importmap.d.ts
-interface ImportMapData {
-  imports?: Record<string, string>;
-  scopes?: Record<string, Record<string, string>>;
+type ModuleSpecifierMap = Map<string, URL | null>;
+interface SpecifierResolutionRecord {
+  serializedBaseURL: string;
+  specifier: string;
+  specifierAsURL: URL | null;
+}
+declare class ImportMap {
+  imports: ModuleSpecifierMap;
+  scopes: Map<string, ModuleSpecifierMap>;
+  integrity: Map<string, string>;
+  constructor(imports?: ModuleSpecifierMap, scopes?: Map<string, ModuleSpecifierMap>, integrity?: Map<string, string>);
+  /** Parse a JSON import map string against a base URL. */
+  static parse(input: string, baseURL: URL | string): ImportMap;
+  /** Build an ImportMap from a plain object (same shape as the JSON format). */
+  static of(json: object, baseURL: URL | string): ImportMap;
+  /** Merge newImportMap into oldImportMap in place (spec § "merge existing and new import maps"). */
+  static merge(oldImportMap: ImportMap, newImportMap: ImportMap, resolvedModuleSet?: ReadonlyArray<SpecifierResolutionRecord>): void;
+  /** Resolve a specifier against an import map (spec § "resolve a module specifier"). */
+  static resolve(specifier: string, importMap: ImportMap, baseURL: string | URL): {
+    url: string;
+    record: SpecifierResolutionRecord;
+  } | undefined;
+  /** Parse all <script type="importmap"> elements from the DOM. */
+  static fromDOM(): ImportMap;
 }
 //#endregion
 //#region src/module-tsx.d.ts
@@ -12,7 +33,7 @@ interface ModuleTSXConfig {
    */
   baseUrl?: string;
   fetch?: (fullURL: string) => Promise<Response>;
-  importMap?: ImportMapData;
+  importMap?: ImportMap;
   /**
    * Given a bare specifier, return a full URL to load the module.
    * This can be used to convert for example import "react" to import "https://esm.sh/react".
@@ -22,16 +43,20 @@ interface ModuleTSXConfig {
   resolveBareSpecifier?: string | ((specifier: string) => string);
 }
 interface ModuleTSXEventMap {
+  /** Fired when an import starts. `id` is the original specifier as passed by the caller. */
   import: CustomEvent<{
     id: string;
   }>;
+  /** Fired when an import fails. `id` is the specifier at the point of failure. */
   "import:error": CustomEvent<{
     id: string;
     error: any;
   }>;
+  /** Fired when a source file starts being transpiled. */
   transform: CustomEvent<{
     sourceUrl: string;
   }>;
+  /** Fired when transpilation fails. */
   "transform:error": CustomEvent<{
     sourceUrl: string;
     error: any;
@@ -39,15 +64,20 @@ interface ModuleTSXEventMap {
 }
 interface IModuleTSX extends EventTarget {
   addEventListener<T extends keyof ModuleTSXEventMap>(type: T, listener: (this: ModuleTSX, ev: ModuleTSXEventMap[T]) => any, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
 }
 declare class ModuleTSX extends EventTarget implements IModuleTSX {
   readonly baseUrl: string;
-  readonly importMap: ImportMapData;
+  readonly importMap: ImportMap;
   readonly fetch: (url: string) => Promise<Response>;
   readonly resolveBareSpecifier: (specifier: string) => string;
+  private readonly resolvedModuleSet;
   private readonly sourceTracker;
   private readonly fetchText;
   constructor(config?: ModuleTSXConfig);
+  /** Add a new import map, merging it into the existing one per the spec.
+   *  Rules that conflict with already-resolved modules are silently dropped. */
+  addImportMap(newImportMap: ImportMap): void;
   private emit;
   import(id: string, options?: any): Promise<any>;
   importCode(sourceUrl: string, code: string, options?: any): Promise<any>;
@@ -55,6 +85,7 @@ declare class ModuleTSX extends EventTarget implements IModuleTSX {
   private transformSourceModule;
   private getLoaderByResourceType;
   private tsxLoader;
+  private resolveLocalUrl;
   private resolveSpecifier;
   private resolveSpecifiers;
 }
@@ -71,4 +102,4 @@ declare class ModuleTSXError extends Error {
  */
 declare const instance: ModuleTSX;
 //#endregion
-export { ModuleTSX, ModuleTSXError, instance };
+export { ImportMap, ModuleTSX, ModuleTSXError, instance };