Simplify readme

Author: airhorns

Readme.md

@@ -24,7 +24,7 @@ export default defineConfig({
   plugins: [
     chatGPTWidgetPlugin({
       widgetsDir: "web/chatgpt-widgets", // default: 'web/chatgpt-widgets'
-      baseUrl: "https://example.com", // required because the chatgpt iframe is sandboxed and absolute URL links are required
+      baseUrl: "https://example.com", // if not using a vite `base`, this is required because the chatgpt iframe is sandboxed and absolute URL links are required
     }),
   ],
   build: {
@@ -38,10 +38,21 @@ export default defineConfig({
 Create React components in your widgets directory:
 
 ```tsx
-// web/chatgpt-widgets/MyWidget.tsx
-export default function MyWidget() {
+// in web/chatgpt-widgets/Hello.tsx
+export default function Hello() {
   return <div>Hello from ChatGPT Widget!</div>;
 }
+
+// in web/chatgpt-widgets/ListFoobars.tsx
+export default function ListFoobars() {
+  return (
+    <ul>
+      {window.openai.tool_output.foobars.map((foobar) => (
+        <li>{foobar}</li>
+      ))}
+    </ul>
+  );
+}
 ```
 
 #### Optional: Root Layout Component
@@ -52,15 +63,10 @@ You can optionally create a root layout component that will wrap all widgets. If
 // web/chatgpt-widgets/root.tsx
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
-    <div className="root-layout">
-      <header>
-        <h1>Common Header</h1>
-      </header>
-      <main>{children}</main>
-      <footer>
-        <p>Common Footer</p>
-      </footer>
-    </div>
+    <SomeProvider>
+      <header>Common Header</header>
+      {children}
+    </SomeProvider>
   );
 }
 ```
@@ -69,24 +75,29 @@ The root layout component:
 
 - Must accept a `children` prop
 - Will automatically wrap every widget component
-- Is not exposed as a widget itself
 - Is optional - if not present, widgets render without a wrapper
 
 ### 3. Serve Widgets in Your Application
 
-#### Development Mode (with Vite Dev Server)
+After setting up the plugin and writing some widgets, you need to expose the widget HTML snippets generated by this plugin as MCP server resources. In development, the HTML snippets will be generated by Vite dynamically, and in production, they'll be built by your Vite build process and read off the disk.
 
 ```typescript
 import { getWidgets } from "vite-plugin-chatgpt-widgets";
 
-// Pass the Vite dev server instance from wherever you can get it
+// In development, pass the Vite dev server instance from wherever you can get it
 const widgets = await getWidgets("web/chatgpt-widgets", viteDevServer);
 
+// In production, pass a path to the vite manifest, where we'll load precompiled versions from
+const widgets = await getWidgets("web/chatgpt-widgets", {
+  manifestPath: "dist/.vite/manifest.json",
+});
+
 // Register each widget on an MCP server as a resource for exposure to ChatGPT
 for (const widget of widgets) {
   const resourceName = `widget-${widget.name.toLowerCase()}`;
   const resourceUri = `ui://widget/${widget.name}.html`;
 
+  // assuming you are using @modelcontextprotocol/sdk, will be similar for other MCP implementations
   mcpServer.registerResource(
     resourceName,
     resourceUri,
@@ -109,45 +120,23 @@ for (const widget of widgets) {
 }
 ```
 
-#### Production Mode (reading from build manifest)
-
-```typescript
-import { getWidgetHTML } from "vite-plugin-chatgpt-widgets";
-
-// Pass production options (or omit for defaults)
-const widgets = await getWidgets("web/chatgpt-widgets", {
-  manifestPath: "dist/.vite/manifest.json",
-  baseUrl: "https://example.com", // required for sandbox-safe iframe links (see below)
-});
-
-for (const widget of widgets) {
-  // ...
-}
-```
-
-### Sandboxed iFrames & Fully Qualified URLs
+### Sandboxed iframes require fully qualified URLs
 
-**⚠️ Required:** When serving widgets in sandboxed iframes like ChatGPT's UI, asset links **must** be fully qualified URLs with protocol and domain. The plugin enforces this requirement and will throw an error if an absolute base URL is not configured.
+When serving widgets in sandboxed iframes like ChatGPT's UI, asset links **must** be fully qualified URLs with protocol and domain. The user's browser loads up your widget on an OpenAI controlled domain, so asset loads must refer directly back to your hosting provider. The plugin enforces this requirement and will throw an error if an absolute base URL is not configured.
 
 You must configure an absolute base URL in one of these ways:
 
-1. **Vite's `base` config is an absolute URL**: If you've already configured Vite with `base: "https://example.com/"`, the plugin will use it automatically.
+1. Vite's `base` config: If you've already configured Vite with `base: "https://example.com/"`, the plugin will use it automatically.
 
 ```typescript
 // Option 1: In Vite config (affects both dev and build)
 export default defineConfig({
   plugins: [chatGPTWidgetPlugin({})],
   base: "https://example.com",
 });
-
-// and when calling getWidgets in production
-const widgets = await getWidgets("web/chatgpt-widgets", {
-  manifestPath: "dist/.vite/manifest.json",
-  baseUrl: "https://example.com",
-});
 ```
 
-2. **Provide `baseUrl` option**: If Vite's `base` is relative (or not set), provide the `baseUrl` option to the plugin or the production build configuration:
+2. `baseUrl` option to this plugin:: If Vite's `base` is not set, or must be relative,, provide the `baseUrl` option to this plugin directly:
 
 ```typescript
 // Option 1: In Vite config (affects both dev and build)
@@ -159,26 +148,8 @@ export default defineConfig({
   ],
   base: "/",
 });
-
-// Option 2: When calling getWidgets in production
-const widgets = await getWidgets("web/chatgpt-widgets", {
-  manifestPath: "dist/.vite/manifest.json",
-  baseUrl: "https://example.com",
-});
 ```
 
-**How it works:**
-
-- The plugin transforms relative asset URLs like `/assets/widget-abc123.js` to `https://example.com/assets/widget-abc123.js`
-- Only the entry `<script>` and `<link>` tags in the HTML are transformed
-- ES module imports within JavaScript files remain relative (correct behavior - the browser resolves them relative to the parent module's URL)
-
-**Validation:**
-
-- At build time: The plugin validates that either Vite's `base` or the plugin's `baseUrl` option is an absolute URL
-- At runtime: `getWidgets()` and `getWidgetHTML()` validate that an absolute base URL is available from either Vite's config or the provided `baseUrl` option
-- If validation fails, an error is thrown with clear instructions on how to fix it
-
 ## How It Works
 
 The plugin creates virtual modules for each widget component:
@@ -209,20 +180,6 @@ Get the HTML content for a widget.
 **Parameters:**
 
 - `widgetsDir` (string): The path to the directory on disk with your widget components
-- `viteHandle` (ViteDevServer | ProductionViteBuild): A reference to a Vite context we can use for getting widget content.
-  - In dev: Pass the Vite dev server instance
-  - In prod: Pass an object with:
-    - `manifestPath` (string): Path to the Vite manifest.json file (e.g., `"dist/.vite/manifest.json"`)
-    - `baseUrl` (string, optional): Base URL for assets if Vite's `base` is not absolute
-
-## Architecture
-
-The plugin and helpers run in different contexts:
-
-- **Plugin context**: Runs during Vite build, creates virtual modules and adds them as entrypoints
-- **Application context**: The helper functions run in your app (e.g., MCP server) to serve the widgets
-
-They communicate via:
-
-- **Dev mode**: Direct access to Vite's dev server plugin container
-- **Production**: Vite's `manifest.json` file maps virtual module IDs to built file paths
+- `viteHandle` (DevelopmentViteBuild | ProductionViteBuild): A reference to a Vite context we can use for getting widget content.
+  - In dev: Pass an object like `{ devServer: ViteDevServer }` to give the Vite dev server to use to build HTML
+  - In prod: Pass an object like `{ mainfest: "some/path/to/.vite/manifest.json" }` to list all the entrypoints built by the vite build process