feat(superdoc): ship IIFE CDN bundle with working vanilla example (#2835)

* feat(superdoc): ship IIFE CDN bundle with working vanilla example

Switch the CDN-facing build from UMD to IIFE, minify it, expose
`window.SuperDoc` as the class directly, and verify end-to-end with a
real DOCX rendering in the existing CDN example.

- Rename vite.config.umd.js to vite.config.cdn.js; format=iife,
  name=SuperDoc, esbuild minify. Bundle drops from 8.8 MB unminified to
  4.9 MB minified (1.46 MB gzipped).
- Add src/cdn-entry.js so `window.SuperDoc` is the constructor and named
  exports attach as static properties (Quill pattern).
- Inline yjs + hocuspocus into the IIFE (ESM-only — can't be loaded as
  script-tag globals). pdfjs-dist stays external; PDF viewing is
  documented as ESM + import-map only.
- Flip package.json "main" from the fat UMD to the proper CJS build,
  add ./global subpath export plus unpkg/jsdelivr fields. Keep
  superdoc.umd.js for one minor cycle as a deprecation-warning shim via
  scripts/emit-umd-alias.cjs; removal scheduled for 2.0.
- Extend scripts/audit-bundle.cjs with size budgets (global.js 5/6 MB,
  es.js 3/4 MB, style.css 150/200 KB).
- Rework examples/getting-started/cdn/ to load the locally built bundle
  via a prepare step, auto-mount a bundled test_file.docx, and include
  jsdelivr snippets in the README.
- Rename tests/umd-smoke -> tests/cdn-smoke; add a second HTML page +
  Playwright test asserting the deprecation warning fires on the old
  filename. Extend examples/__tests__/smoke.spec.ts with cdn-specific
  assertions (window.SuperDoc shape, real DOCX renders content).
- Add CDN quickstart to packages/superdoc/AGENTS.md with script-tag and
  ESM + import-map copy-paste blocks and SRI guidance.

* refactor(superdoc): drop UMD deprecation shim

The old superdoc.umd.js was broken for browser use (wrong external
globals, ReferenceError on load). No deprecation window needed for
something that didn't work. Remove emit-umd-alias.cjs, the UMD alias
test, and the build:cdn pipe to it. Fix AGENTS.md to note that Yjs is
inlined (only pdfjs-dist stays external).

* docs: switch CDN examples to superdoc.global.js

Update docs to use the new global bundle:
- Live <SuperDocEditor> and <DocCounter> components (embedded in
  Mintlify pages) now load superdoc.global.js and use window.SuperDoc
  instead of the removed SuperDocLibrary namespace.
- vanilla-js.mdx and quickstart.mdx lead with the <script> tag
  approach; ES modules + import map kept as the secondary option.
- Swap unpkg URLs for jsdelivr.

* refactor(superdoc): rename superdoc.global.js to superdoc.min.js

The `.global.js` suffix was borrowed from Vue's build convention, but
SuperDoc is framework-agnostic to consumers — we shouldn't default
internal conventions to Vue. `.min.js` is the widely-understood name
used by Quill, TinyMCE, lodash, jQuery, and Three.js.

- Rename output file and all references across vite config, audit
  script, package.json exports (including ./min subpath), smoke tests,
  CDN example, AGENTS.md, and live docs components.
- Tidy `loadSuperDocLibrary` -> `loadSuperDoc` in the live Mintlify
  SuperDocEditor component.

* fix(superdoc): address review feedback on CDN bundle

Round-1 review surfaced one blocker and several real issues. All
verified before changing.

Blocker:
- Regenerate pnpm-lock.yaml — the cdn-smoke rename left the lockfile
  pointing at the old umd-smoke entry, so `pnpm install --frozen-lockfile`
  failed in CI before the build step.

Smoke test was a false-positive engine:
- `tests/cdn-smoke/index.html` set `__SUPERDOC_READY__` synchronously
  on the line after `new SuperDoc(...)`, so async init failures still
  passed the test. Move the flag into `onReady` and switch the test to
  `page.waitForFunction`, matching the CDN-example pattern.
- Strengthen the CDN example assertion to check for "Lorem ipsum" from
  the bundled sample DOCX, so editor chrome alone can't satisfy it.

Docs / packaging cleanup:
- Drop the `./min` and `./min.js` subpath exports from package.json —
  they advertised an IIFE as an importable module, but `require()`
  returns `{}`. The `unpkg`/`jsdelivr` fields cover real CDN delivery.
- Replace `@1.27` pins (the package is at 1.26.0) with `@latest` in
  AGENTS.md and the cdn example README; document version pinning in
  the production-pinning section instead.
- Make Quickstart "Mount the editor" step tab-aware so a CDN reader
  doesn't fall into a `<script type="module">` snippet they can't run.
- Update apps/docs/README.md and root `dev:docs` script — both still
  referenced the removed `watch:umd` / UMD wording.

Hardening:
- Audit-bundle now fails loudly if `superdoc.min.js`, `superdoc.es.js`,
  or `style.css` is missing after a full build instead of silently
  skipping the size check.
- prepare.mjs leads with the fix command before the missing-file list,
  drops the dead `mkdirSync` guard.

* fix(superdoc): rename cdn example prepare→setup to avoid pnpm lifecycle hook

`prepare` is a reserved npm/pnpm lifecycle script — it auto-runs after
every `pnpm install`. The cdn example's `prepare` copies built artifacts
from `packages/superdoc/dist/`, but those don't exist at install time on
a fresh clone (or in CI before the build step), so install fails with
exit 1 before anything can build.

Rename to `setup` so it only runs when explicitly invoked by `pnpm dev`
or the Playwright config.

* fix(superdoc): invoke cdn example setup via node directly

The CI `getting-started` job restores a cached workspace but doesn't
install pnpm on PATH, so Playwright's webServer command
`pnpm --dir ... run setup` exits with "pnpm: not found". Other examples
avoid this because their runner falls back to `npm run --prefix` when
local node_modules exist.

Call `node setup.mjs` directly — no package manager dependency, no
script-name coupling, works identically in dev and CI.

* fix(superdoc): don't fail audit-bundle on partial builds

The missing-file gate I added in round-2 of review broke the SDK
validation pipeline, which runs `build:es` (producing superdoc.es.js
only, not superdoc.min.js). The gate assumed "es.js present = full
build, so min.js must exist too" — wrong.

`build:cdn` fails loudly on its own if the CDN bundle is broken, so a
second gate here was double-counting. Revert to the plain `continue`
behaviour for missing files. Size budgets still enforce hard failures
when files ARE present and too big.

* test(superdoc): unit test cdn-entry namespace attachment

Codecov flagged src/cdn-entry.js as 0% covered because its only
exercisers are the Playwright smoke tests, which Codecov doesn't see.
The round-1 review also asked for a direct test of the attach loop —
if a named export silently drops due to a Function intrinsic
collision, the smoke test's spot-checks (createTheme, DOCX) wouldn't
catch an unrelated export going missing.

Three checks: default export is the SuperDoc constructor, every
non-default/non-SuperDoc named export from index.js lands on the
class as a static property, and Function intrinsics (name, prototype)
aren't clobbered.

* fix: update demos and tighten cdn-entry test for round-2 review

Final review flagged three loose ends before merge:

1. In-repo demos still referenced the removed `superdoc.umd.js` and
   `window.SuperDocLibrary`. They passed CI because `@latest` on
   unpkg/jsDelivr still resolves to the pre-merge 1.26.0 tarball, but
   they'd 404 and `ReferenceError` the moment a newer release lands
   without those names. Fixed:
   - `demos/cdn/index.html` — jsDelivr URL, `<script>` (not module),
     `new SuperDoc(...)`.
   - `demos/word-addin/server/public/{editor.html,editor.js}` — same
     treatment, plus swapped the nonsensical pinned `superdoc@.21.0-next.1`
     for the current package alias.
   - `demos/chrome-extension/` — replaced the vendored 4.8 MB
     `lib/superdoc.umd.js` with a fresh `lib/superdoc.min.js`, updated
     manifest + content.js + README to match. All `SuperDocLibrary.*`
     calls (and a couple of error strings) now reference `SuperDoc`.

2. `cdn-entry.test.js` was checking `!== undefined` for each attached
   static, which a stale wrapper or wrong-identity re-export would
   silently pass. Assert `SuperDoc[key] === namespace[key]` instead,
   and add a check that `SuperDoc.SuperDoc` / `SuperDoc.default` don't
   leak through the attach loop.

3. PR body still claimed the old `superdoc.umd.js` "still works for
   now" — that was true when the shim existed; it was dropped in
   `91725cd0a`. Updated the PR body separately to reflect the actual
   shipped migration story.

* fix(demo): use local build in demos/cdn so smoke test passes pre-release

Pointing the CDN demo at jsDelivr @latest 404s until a superdoc release
containing superdoc.min.js publishes — 1.26.0 only has superdoc.umd.js.
CI's DEMO=cdn smoke test caught this (three console errors from the
missing script and stylesheet).

Mirror the pattern from examples/getting-started/cdn: add setup.mjs
that copies the locally built bundle + style.css into the demo dir,
point index.html at the local copies, and keep the jsDelivr URLs as
an inline comment + in the README as the production recipe.

Verified locally: DEMO=cdn playwright test passes (1/1).

Author: caio-pizzol

.github/workflows/ci-superdoc.yml

@@ -171,13 +171,13 @@ jobs:
         if: matrix.name == 'other-packages'
         run: pnpm test:slow
 
-      - name: Install Playwright for UMD smoke test
+      - name: Install Playwright for CDN smoke test
         if: matrix.name == 'other-packages'
-        run: pnpm --filter @superdoc/umd-smoke-test exec playwright install --with-deps chromium
+        run: pnpm --filter @superdoc/cdn-smoke-test exec playwright install --with-deps chromium
 
-      - name: Run UMD smoke test
+      - name: Run CDN smoke test
         if: matrix.name == 'other-packages'
-        working-directory: packages/superdoc/tests/umd-smoke
+        working-directory: packages/superdoc/tests/cdn-smoke
         run: pnpm test
 
   cli-tests:

apps/docs/README.md

@@ -47,11 +47,11 @@ pnpm dev:docs
 
 This starts three processes:
 
-- **Vite dev server** (port 9094) — serves the built UMD bundle at `/dist`
-- **UMD watcher** — rebuilds `dist/superdoc.umd.js` automatically when source files change
+- **Vite dev server** (port 9094) — serves the built CDN bundle at `/dist`
+- **CDN watcher** — rebuilds `dist/superdoc.min.js` automatically when source files change
 - **Mintlify** (port 3001) — the docs dev server
 
-The `<SuperDocEditor>` widget detects `localhost` and loads SuperDoc from the local Vite server instead of unpkg. After saving a source file, the UMD watcher rebuilds automatically — refresh the docs page to see the changes.
+The `<SuperDocEditor>` widget detects `localhost` and loads SuperDoc from the local Vite server instead of jsDelivr. After saving a source file, the CDN watcher rebuilds automatically — refresh the docs page to see the changes.
 
 ### Available Scripts
 

apps/docs/getting-started/frameworks/vanilla-js.mdx

@@ -96,6 +96,7 @@ new SuperDoc({
 <head>
   <link href="https://cdn.jsdelivr.net/npm/superdoc/dist/style.css"
         rel="stylesheet">
+  <script src="https://cdn.jsdelivr.net/npm/superdoc/dist/superdoc.min.js"></script>
 </head>
 <body>
   <div class="controls">
@@ -107,9 +108,7 @@ new SuperDoc({
 
   <div id="editor" style="height: 700px"></div>
 
-  <script type="module">
-    import { SuperDoc } from 'https://cdn.jsdelivr.net/npm/superdoc/dist/superdoc.es.js';
-    
+  <script>
     let superdoc = null;
     
     document.getElementById('file-input').addEventListener('change', (e) => {

apps/docs/getting-started/quickstart.mdx

@@ -123,27 +123,41 @@ Done. Ask your agent to open a `.docx` file and make an edit.
       <Tab title="CDN">
         ```html
         <link href="https://cdn.jsdelivr.net/npm/superdoc/dist/style.css" rel="stylesheet">
-        <script type="module">
-          import { SuperDoc } from 'https://cdn.jsdelivr.net/npm/superdoc/dist/superdoc.es.js';
-        </script>
+        <script src="https://cdn.jsdelivr.net/npm/superdoc/dist/superdoc.min.js"></script>
         ```
+        `SuperDoc` becomes a global — use `new SuperDoc({...})` directly.
       </Tab>
     </Tabs>
   </Step>
 
   <Step title="Mount the editor">
-    ```html
-    <div id="editor" style="height: 100vh"></div>
+    <Tabs>
+      <Tab title="npm">
+        ```html
+        <div id="editor" style="height: 100vh"></div>
 
-    <script type="module">
-      import { SuperDoc } from 'superdoc';
-      import 'superdoc/style.css';
+        <script type="module">
+          import { SuperDoc } from 'superdoc';
+          import 'superdoc/style.css';
 
-      const superdoc = new SuperDoc({
-        selector: '#editor',
-      });
-    </script>
-    ```
+          const superdoc = new SuperDoc({
+            selector: '#editor',
+          });
+        </script>
+        ```
+      </Tab>
+      <Tab title="CDN">
+        ```html
+        <div id="editor" style="height: 100vh"></div>
+
+        <script>
+          const superdoc = new SuperDoc({
+            selector: '#editor',
+          });
+        </script>
+        ```
+      </Tab>
+    </Tabs>
     That's a blank editor. Now give it a file.
   </Step>
 

apps/docs/snippets/components/doc-counter.jsx

@@ -13,17 +13,17 @@ export const DocCounter = ({ height = '350px' }) => {
   useEffect(() => {
     const link = document.createElement('link');
     link.rel = 'stylesheet';
-    link.href = 'https://unpkg.com/superdoc@latest/dist/style.css';
+    link.href = 'https://cdn.jsdelivr.net/npm/superdoc@latest/dist/style.css';
     document.head.appendChild(link);
 
-    // Buffer polyfill — required by the UMD build for document hashing
+    // Buffer polyfill — required for document hashing
     const bufferScript = document.createElement('script');
     bufferScript.src = 'https://cdn.jsdelivr.net/npm/buffer@6/index.min.js';
     bufferScript.onload = () => {
       window.Buffer = window.buffer.Buffer;
 
       const script = document.createElement('script');
-      script.src = 'https://unpkg.com/superdoc@latest/dist/superdoc.umd.js';
+      script.src = 'https://cdn.jsdelivr.net/npm/superdoc@latest/dist/superdoc.min.js';
       script.onload = () => setTimeout(() => initializeSuperdoc(), 100);
       document.body.appendChild(script);
     };
@@ -95,8 +95,8 @@ export const DocCounter = ({ height = '350px' }) => {
       config.html = '<p>Upload a DOCX file to see how document counting works.</p>';
     }
 
-    if (window.SuperDocLibrary) {
-      superdocRef.current = new window.SuperDocLibrary.SuperDoc(config);
+    if (window.SuperDoc) {
+      superdocRef.current = new window.SuperDoc(config);
     }
   };
 

apps/docs/snippets/components/superdoc-editor.jsx

@@ -17,7 +17,7 @@ export const SuperDocEditor = ({
 
     if (isDev) {
       try {
-        const res = await fetch(`${DEV_DIST_URL}/superdoc.umd.js`, { method: 'HEAD' });
+        const res = await fetch(`${DEV_DIST_URL}/superdoc.min.js`, { method: 'HEAD' });
         if (res.ok) {
           console.info('[SuperDoc Docs] Using local build from', DEV_DIST_URL);
           return DEV_DIST_URL;
@@ -45,14 +45,14 @@ export const SuperDocEditor = ({
     document.head.appendChild(link);
   };
 
-  const loadSuperDocLibrary = (baseUrl) => {
-    if (window.SuperDocLibrary) return Promise.resolve();
+  const loadSuperDoc = (baseUrl) => {
+    if (window.SuperDoc) return Promise.resolve();
 
-    const scriptSrc = `${baseUrl}/superdoc.umd.js`;
+    const scriptSrc = `${baseUrl}/superdoc.min.js`;
     const existingScript = document.querySelector(`script[src="${scriptSrc}"]`);
 
     if (existingScript) {
-      if (window.SuperDocLibrary) return Promise.resolve();
+      if (window.SuperDoc) return Promise.resolve();
 
       return new Promise((resolve, reject) => {
         existingScript.addEventListener('load', resolve, { once: true });
@@ -71,11 +71,11 @@ export const SuperDocEditor = ({
 
   const initEditor = () => {
     setTimeout(() => {
-      if (!window.SuperDocLibrary) return;
+      if (!window.SuperDoc) return;
       if (!document.getElementById(containerIdRef.current)) return;
       if (editorRef.current) return;
 
-      editorRef.current = new window.SuperDocLibrary.SuperDoc({
+      editorRef.current = new window.SuperDoc({
         selector: `#${containerIdRef.current}`,
         html,
         rulers: true,
@@ -95,7 +95,7 @@ export const SuperDocEditor = ({
       try {
         const baseUrl = await getBaseUrl();
         ensureStyle(baseUrl);
-        await loadSuperDocLibrary(baseUrl);
+        await loadSuperDoc(baseUrl);
         if (!cancelled) initEditor();
       } catch (error) {
         console.error('Failed to boot SuperDoc:', error);

demos/cdn/.gitignore

@@ -0,0 +1,2 @@
+superdoc.min.js
+style.css

demos/cdn/index.html

@@ -1,8 +1,15 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-  <link rel="stylesheet" href="https://unpkg.com/superdoc/dist/style.css">
-  <script type="module" src="https://unpkg.com/superdoc/dist/superdoc.umd.js"></script>
+  <!--
+    For production use, load from jsDelivr and pin a version:
+      <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/superdoc/dist/style.css">
+      <script src="https://cdn.jsdelivr.net/npm/superdoc/dist/superdoc.min.js"></script>
+    This demo uses local copies (populated by setup.mjs) so it runs against
+    in-tree builds in CI before a release is published.
+  -->
+  <link rel="stylesheet" href="./style.css">
+  <script src="./superdoc.min.js"></script>
   <link rel="stylesheet" href="./file-upload.css">
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -28,7 +35,7 @@
 
   <div id="superdoc"></div>
 
-  <script type="module">
+  <script>
     const config = {
       selector: '#superdoc',
       toolbar: '#my-toolbar',
@@ -44,10 +51,10 @@
       },
     };
 
-    const superdoc = new SuperDocLibrary.SuperDoc(config);
+    let superdoc = new SuperDoc(config);
 
     window.addEventListener('file-upload', (event) => {
-      new SuperDocLibrary.SuperDoc({...config, document: event.detail}); 
+      superdoc = new SuperDoc({ ...config, document: event.detail });
     });
   </script>
   <script type="module" src="./file-upload.js"></script>

demos/cdn/package.json

@@ -4,8 +4,8 @@
   "description": "This is a very basic example of loading SuperDoc from CDN without any bundlers.",
   "main": "index.js",
   "scripts": {
-    "dev": "http-server",
-    "start": "http-server",
+    "dev": "node ./setup.mjs && http-server",
+    "start": "node ./setup.mjs && http-server",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [],

demos/cdn/setup.mjs

@@ -0,0 +1,29 @@
+// Copies the locally built CDN bundle into this demo dir so `index.html` is
+// self-contained and can be served with `http-server`. The README still shows
+// the jsDelivr URLs as the recommended production recipe.
+
+import { copyFileSync, existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const dist = resolve(here, '../../packages/superdoc/dist');
+
+const assets = [
+  [resolve(dist, 'superdoc.min.js'), resolve(here, 'superdoc.min.js')],
+  [resolve(dist, 'style.css'), resolve(here, 'style.css')],
+];
+
+const missing = assets.filter(([src]) => !existsSync(src));
+if (missing.length) {
+  console.error('[cdn-demo/setup] Build the SuperDoc bundle first:');
+  console.error('  pnpm --filter superdoc build');
+  console.error('Missing files:');
+  for (const [src] of missing) console.error('  ' + src);
+  process.exit(1);
+}
+
+for (const [src, dst] of assets) {
+  copyFileSync(src, dst);
+  console.log('[cdn-demo/setup] copied', dst.replace(here + '/', ''));
+}