docs: update README with enhanced usage instructions and new features section

Author: YieldRay

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,50 @@ 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));
+```
+
+## 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>
+```

docs/src/pages/ApiReference.tsx

@@ -2,7 +2,7 @@ import React from "react";
 import { Table } from "soda-material";
 import CodeBlock from "../components/CodeBlock.tsx";
 
-const CONSTRUCTOR_EXAMPLE = `import { ModuleTSX } from "https://yieldray.github.io/module-tsx/dist/index.mjs";
+const CONSTRUCTOR_EXAMPLE = `import { ModuleTSX } from "https://esm.sh/module-tsx";
 
 const instance = new ModuleTSX({
   baseUrl: "https://my-site.com/app/",
@@ -24,7 +24,7 @@ const code = \`
 const mod = await instance.importCode("https://my-site.com/", code);
 mod.greet("World"); // "Hello, World!"`;
 
-const EVENTS_EXAMPLE = `import { instance } from "https://yieldray.github.io/module-tsx/dist/index.mjs";
+const EVENTS_EXAMPLE = `import { instance } from "https://esm.sh/module-tsx";
 
 // Listen to all events
 instance.addEventListener("*", (e) => {
@@ -49,18 +49,18 @@ instance.addEventListener("transform:error", (e) => {
 });`;
 
 const SINGLETON_EXAMPLE = `<!-- The singleton instance auto-processes <script type="module-tsx"> tags -->
-<script type="module" src="https://yieldray.github.io/module-tsx/dist/index.mjs"></script>
+<script type="module" src="https://esm.sh/module-tsx"></script>
 <script type="module-tsx" src="./src/main.tsx"></script>
 
 <!-- Access the singleton from another module script -->
 <script type="module">
-  import { instance } from "https://yieldray.github.io/module-tsx/dist/index.mjs";
+  import { instance } from "https://esm.sh/module-tsx";
   instance.addEventListener("transform", (e) => {
     console.log("Transformed:", e.detail.sourceUrl);
   });
 </script>`;
 
-const CUSTOM_CDN_EXAMPLE = `import { ModuleTSX } from "https://yieldray.github.io/module-tsx/dist/index.mjs";
+const CUSTOM_CDN_EXAMPLE = `import { ModuleTSX } from "https://esm.sh/module-tsx";
 
 // Use a string prefix (appended to bare specifier)
 const instance = new ModuleTSX({

docs/src/pages/BasicUsage.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 import CodeBlock from "../components/CodeBlock.tsx";
 
-const INLINE_SCRIPT = `<script type="module" src="https://yieldray.github.io/module-tsx/dist/index.mjs"></script>
+const INLINE_SCRIPT = `<script type="module" src="https://esm.sh/module-tsx"></script>
 
 <!-- Inline TypeScript/JSX directly in your HTML -->
 <script type="module-tsx">
@@ -12,7 +12,7 @@ const INLINE_SCRIPT = `<script type="module" src="https://yieldray.github.io/mod
   createRoot(root).render(<h1>Hello from inline TSX!</h1>);
 </script>`;
 
-const EXTERNAL_SCRIPT = `<script type="module" src="https://yieldray.github.io/module-tsx/dist/index.mjs"></script>
+const EXTERNAL_SCRIPT = `<script type="module" src="https://esm.sh/module-tsx"></script>
 
 <!-- Reference an external .tsx file -->
 <script type="module-tsx" src="./src/main.tsx"></script>`;
@@ -42,15 +42,14 @@ export default function BasicUsage() {
 
       <h2>Inline Scripts</h2>
       <p>
-        Write TypeScript and JSX directly inside a{" "}
-        <code>{"<script type=\"module-tsx\">"}</code> tag:
+        Write TypeScript and JSX directly inside a <code>{'<script type="module-tsx">'}</code> tag:
       </p>
       <CodeBlock code={INLINE_SCRIPT} language="html" />
 
       <h2>External Files</h2>
       <p>
-        Reference an external <code>.tsx</code> file using the <code>src</code> attribute.
-        module-tsx will fetch, compile, and execute it:
+        Reference an external <code>.tsx</code> file using the <code>src</code> attribute. module-tsx will fetch,
+        compile, and execute it:
       </p>
       <CodeBlock code={EXTERNAL_SCRIPT} language="html" />
       <p>The entry file can import other local files using relative paths:</p>
@@ -59,9 +58,8 @@ export default function BasicUsage() {
 
       <h2>The async Attribute</h2>
       <p>
-        By default, multiple <code>{"<script type=\"module-tsx\">"}</code> tags execute
-        sequentially — each one waits for the previous to finish. Add the <code>async</code>{" "}
-        attribute to execute them concurrently:
+        By default, multiple <code>{'<script type="module-tsx">'}</code> tags execute sequentially — each one waits for
+        the previous to finish. Add the <code>async</code> attribute to execute them concurrently:
       </p>
       <CodeBlock code={ASYNC_SCRIPT} language="html" />
     </article>

docs/src/pages/GettingStarted.tsx

@@ -10,7 +10,7 @@ const QUICK_START = `<!doctype html>
     <div id="root"></div>
 
     <!-- 1. Load module-tsx from CDN -->
-    <script type="module" src="https://yieldray.github.io/module-tsx/dist/index.mjs"></script>
+    <script type="module" src="https://esm.sh/module-tsx"></script>
 
     <!-- 2. Write TypeScript/React directly -->
     <script type="module-tsx">
@@ -36,9 +36,8 @@ export default function GettingStarted() {
     <article>
       <h1 className="text-4xl font-bold mt-0">Getting Started</h1>
       <p className="text-lg leading-relaxed text-[var(--md-sys-color-on-surface-variant)]">
-        <strong>module-tsx</strong> lets you run TypeScript and React directly in the browser —
-        no build step, no npm install, no bundler required. You publish source code and users run
-        it instantly.
+        <strong>module-tsx</strong> lets you run TypeScript and React directly in the browser — no build step, no npm
+        install, no bundler required. You publish source code and users run it instantly.
       </p>
 
       <h2>Quick Start</h2>
@@ -47,22 +46,20 @@ export default function GettingStarted() {
 
       <h2>Serve Locally</h2>
       <p>
-        Because module-tsx fetches your source files via HTTP, you need to serve your project
-        from a local server (not <code>file://</code>):
+        Because module-tsx fetches your source files via HTTP, you need to serve your project from a local server (not{" "}
+        <code>file://</code>):
       </p>
       <CodeBlock code={SERVE_CMD} language="bash" />
 
       <h2>How It Works</h2>
       <p>
-        When the page loads, module-tsx finds every{" "}
-        <code>{"<script type=\"module-tsx\">"}</code> tag, fetches and transforms the
-        TypeScript/JSX source using the TypeScript compiler running in the browser, then executes
-        the result as an ES module via a Blob URL.
+        When the page loads, module-tsx finds every <code>{`<script type="module-tsx">`}</code> tag, fetches and
+        transforms the TypeScript/JSX source using the TypeScript compiler running in the browser, then executes the
+        result as an ES module via a Blob URL.
       </p>
       <p>
-        Bare specifiers like <code>import React from "react"</code> are automatically resolved
-        to <code>https://esm.sh/react</code>. You can use any npm package without installing
-        anything.
+        Bare specifiers like <code>import React from "react"</code> are automatically resolved to{" "}
+        <code>https://esm.sh/react</code>. You can use any npm package without installing anything.
       </p>
     </article>
   );

docs/src/pages/TypeScriptSupport.tsx

@@ -31,7 +31,7 @@ export default function TypeScriptSupport() {
       <p>
         module-tsx uses the TypeScript compiler (running in the browser) to transpile your code
         before execution. You can write full TypeScript syntax — interfaces, generics, enums,
-        type assertions — directly inside <code>{"<script type=\"module-tsx\">"}</code> tags or
+        type assertions — directly inside <code>{`<script type="module-tsx">`}</code> tags or
         in <code>.ts</code> / <code>.tsx</code> files.
       </p>
 

src/index.ts

@@ -29,7 +29,7 @@ async function sideEffect() {
       );
     }
     for (const key in ["integrity", "crossorigin"] as (keyof HTMLScriptElement)[]) {
-      if (script[key]) {
+      if (script[key as keyof HTMLScriptElement]) {
         warn(`script with type="${TYPE_ATTRIBUTE_VALUE}" does not support ${key} attribute.`);
       }
     }
@@ -42,4 +42,9 @@ async function sideEffect() {
   }
 }
 
+/**
+ * Since this module can be loaded as both ESM and UMD, we listen for DOMContentLoaded to ensure all type="module-tsx" tags are present.
+ * ESM scripts are always deferred, so the document is already fully parsed when this module executes and the listener fires immediately.
+ * Classic scripts run inline as the parser encounters them, so they must wait for DOMContentLoaded.
+ */
 document.addEventListener("DOMContentLoaded", sideEffect);

src/module-tsx.ts

@@ -32,9 +32,13 @@ interface ModuleTSXConfig {
 }
 
 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 }>;
 }
 
@@ -44,6 +48,11 @@ interface IModuleTSX extends EventTarget {
     listener: (this: ModuleTSX, ev: ModuleTSXEventMap[T]) => any,
     options?: boolean | AddEventListenerOptions,
   ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
 }
 
 export class ModuleTSX extends EventTarget implements IModuleTSX {
@@ -100,9 +109,13 @@ export class ModuleTSX extends EventTarget implements IModuleTSX {
   }
 
   public async importCode(sourceUrl: string, code: string, options?: any): Promise<any> {
-    const transformedUrl = await this.transformSourceModule("esm", sourceUrl, code);
-    const module = await import(transformedUrl, options);
-    return module;
+    try {
+      const transformedUrl = await this.transformSourceModule("esm", sourceUrl, code);
+      return await import(transformedUrl, options);
+    } catch (error) {
+      this.emit("import:error", { id: sourceUrl, error });
+      throw error;
+    }
   }
 
   /** Transform module source code and return a blob URL with the transformed content */