From a73f1189ed773d41b9cc20e414ed0fda2cfcefb7 Mon Sep 17 00:00:00 2001
From: Jordan Paulino <jjpaulino@users.noreply.github.com>
Date: Fri, 15 May 2026 13:49:14 -0400
Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=8D=95=20Clarify=20=5Fclient-init.js?=
 =?UTF-8?q?=20component-mounting=20semantics=20in=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Several places in CLAY-VITE.md and BUNDLER-COMPARISON.md described the
legacy Browserify component loader as "mounts every .client module
loaded — no DOM check" or "DOM or not". That overstates what
_client-init.js actually does.

Per lib/cmd/compile/_client-init.js, mountComponentModules() iterates
every .client key in window.modules and calls window.require(key) on
each — which executes the module body and walks its dependency graph
regardless of DOM presence — but the exported controller function is
only invoked via tryToMount() for elements matching the
[data-uri*="_components/<name>/"] / [data-uri$="_components<name>"]
selectors. So the mount call itself IS DOM-gated; what isn't gated is
module evaluation.

The Vite improvement is therefore narrower but still real: vite-bootstrap
scans the DOM first and skips the dynamic import() entirely if no
matching element exists, so neither the module body nor any of its
transitive dependencies execute. Updated all four prose locations to
reflect this; the mermaid diagrams already used the more precise
"calls window.require(key) for every .client / regardless of DOM
presence" wording and were left as-is.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 BUNDLER-COMPARISON.md | 4 +++-
 CLAY-VITE.md          | 6 +++---
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/BUNDLER-COMPARISON.md b/BUNDLER-COMPARISON.md
index 9c41158..2054220 100644
--- a/BUNDLER-COMPARISON.md
+++ b/BUNDLER-COMPARISON.md
@@ -45,7 +45,9 @@ Browserify + Babel (30–60 s)
     ▼
 _prelude.js / _postlude.js  ← shipped to every page
 _registry.json + _ids.json  ← opaque numeric dep graph
-_client-init.js             ← mounts every .client module loaded, DOM or not
+_client-init.js             ← calls window.require() on every .client module
+                              (runs body + deps even if no DOM element exists);
+                              controller invocation itself is DOM-gated
 ```
 
 ### Problems
diff --git a/CLAY-VITE.md b/CLAY-VITE.md
index 03bda00..486744f 100644
--- a/CLAY-VITE.md
+++ b/CLAY-VITE.md
@@ -259,7 +259,7 @@ flowchart LR
 | **JS tool** | Browserify + Babel (megabundles) | Vite (Rollup 4 + manualChunks) | 🔄 Replaced |
 | **CSS tool** | Gulp + PostCSS 7 | PostCSS 8 programmatic API | 🔄 Replaced; same plugin ecosystem |
 | **Module graph** | `_registry.json` + `_ids.json` | `_manifest.json` (human-readable) | ⚠️ Different format; same purpose |
-| **Component loader** | `_client-init.js` — mounts every `.client` module loaded | `vite-bootstrap.js` — mounts only when DOM element present | ✅ Better; avoids dead code execution |
+| **Component loader** | `_client-init.js` — calls `window.require()` on every `.client` module (executing its body and dependency graph), then DOM-checks before invoking the exported controller | `vite-bootstrap.js` — scans the DOM first; only `import()`s a `.client` module if its element exists | ✅ Better; module body never executes for components absent from the page |
 | **JS output** | Per-component files + alpha-bucket dep files | Dynamic import splits + `chunks/` shared deps | ✅ Better; shared deps cached once |
 
 ### 4b. JS module system architecture
@@ -339,7 +339,7 @@ flowchart TB
 | Concern | `clay compile` | `clay vite` | Why it matters |
 |---|---|---|---|
 | **Module registry** | Runtime: `window.modules` built as scripts evaluate | Build-time: `_manifest.json` written once | Old: any code could `window.require()` at any time. New: all wiring is static. |
-| **Component mounting** | `_client-init.js` mounts every loaded `.client` module, DOM or not | `vite-bootstrap.js` scans DOM; only imports a component if its element exists | New: no dead component code execution |
+| **Component mounting** | `_client-init.js` calls `window.require()` on every `.client` (running its body and dep graph) before DOM-gating the controller invocation | `vite-bootstrap.js` scans the DOM first; only imports a component if its element exists | New: no module body or transitive imports run for components absent from the page |
 | **Edit-mode aggregator** | `window.modules` registry | `_kiln-edit-init.js` pre-registers all model/kiln files on `window.kiln.componentModels` | New: explicit pre-wiring, backward compatible |
 | **Shared deps** | Alpha-bucketed dep files (`_deps-a.js`…) — static filenames | Named content-hashed chunks in `public/js/chunks/` | New: unchanged chunks stay cached across deploys |
 | **Global scripts** | Individual `<script>` tags per file | One `_globals-init.js` — 1 request instead of 70–100 | New: fewer network round-trips |
@@ -397,7 +397,7 @@ absent on the next deploy → old path activates. No code changes needed in the
 | **Output filenames** | Static: `article.client.js` | Content-hashed: `chunks/client-A1B2C3.js` |
 | **Module runtime** | `_prelude.js` + `_postlude.js` (custom `window.require`) | Native ESM — no runtime overhead |
 | **Module graph** | `_registry.json` (numeric IDs) + `_ids.json` | `_manifest.json` (human-readable keys) |
-| **Component loader** | `_client-init.js` mounts every `.client` module in `window.modules` | `vite-bootstrap.js` mounts only when DOM element exists |
+| **Component loader** | `_client-init.js` calls `window.require()` on every `.client` in `window.modules` (always executing the module body), then only invokes the controller for matching DOM elements | `vite-bootstrap.js` only imports a `.client` when its DOM element exists, so the module body never runs otherwise |
 | **Chunk size control** | None — all or nothing per alpha-bucket | `manualChunksMinSize` — private deps inlined below threshold |
 | **CJS circular deps** | Implicit (flat scope) | Explicit via `@rollup/plugin-commonjs strictRequires:'auto'` |
 | **Tree shaking** | None | ESM packages: export-level; CJS: `process.env` dead-code elimination |

From 7744fd5a38a708e2f2a603e1028f0e23c5fa7031 Mon Sep 17 00:00:00 2001
From: Jordan Paulino <jjpaulino@users.noreply.github.com>
Date: Wed, 27 May 2026 22:12:58 -0400
Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=8D=95=20Improve=20Vite=20mount=20err?=
 =?UTF-8?q?or=20diagnostics=20and=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Emit structured preload/load/mount error details in the generated Vite bootstrap and document concrete console output so developers can quickly identify failing component phases, URIs, and stack context.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 CLAY-VITE.md                       |  53 ++++++++++++
 lib/cmd/vite/generate-bootstrap.js | 125 +++++++++++++++++++++++++++--
 lib/cmd/vite/generators.test.js    |   2 +
 3 files changed, 172 insertions(+), 8 deletions(-)

diff --git a/CLAY-VITE.md b/CLAY-VITE.md
index 486744f..271f8fe 100644
--- a/CLAY-VITE.md
+++ b/CLAY-VITE.md
@@ -1292,6 +1292,59 @@ into megabundles and never complained about Node-only packages. Under Vite, unre
 Node built-ins produce explicit build errors or runtime crashes. `serviceRewritePlugin`
 automatically redirects `services/server/*` to `services/client/*` in browser builds.
 
+### Debugging component preload/load/mount failures
+
+`vite-bootstrap.js` now logs structured error diagnostics for each component failure phase:
+
+- `preload` — module prefetch failed while scanning Clay comment markers.
+- `load` — dynamic `import()` failed for a component `client.js`.
+- `mount` — module loaded, but the exported controller threw while running.
+- `ds-mount` — Dollar Slice fallback `window.DS.get()` threw.
+
+Each failure includes component identity + URI context (`phase`, `component`, `moduleKey`,
+`uri`) and a normalized error object (`name`, `message`, `stack`, optional `code`, optional
+recursive `cause`).
+
+Example browser console output:
+
+```text
+[clay vite] mount errors (2)
+┌─────────┬──────────┬────────────────┬─────────────────────────────────────┬──────────────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────────┐
+│ (index) │  phase   │   component    │              moduleKey              │                             uri                              │                           message                           │
+├─────────┼──────────┼────────────────┼─────────────────────────────────────┼──────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────┤
+│    0    │ 'load'   │ 'comments-link'│ 'components/comments-link/client.js'│ '/_components/comments-link/instances/cmp123'                │ 'Init must be called with `name` property'                  │
+│    1    │ 'mount'  │ 'auth-modal'   │ 'components/auth-modal/client.js'   │ '/_components/auth-modal/instances/cmp456'                   │ \"Cannot read properties of null (reading 'textContent')\"   │
+└─────────┴──────────┴────────────────┴─────────────────────────────────────┴──────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────────────┘
+
+[clay vite] mount error details [
+  {
+    phase: 'load',
+    component: 'comments-link',
+    moduleKey: 'components/comments-link/client.js',
+    uri: '/_components/comments-link/instances/cmp123',
+    error: {
+      name: 'Error',
+      message: 'Init must be called with `name` property',
+      stack: 'Error: Init must be called with `name` property\\n    at ...'
+    }
+  },
+  {
+    phase: 'mount',
+    component: 'auth-modal',
+    moduleKey: 'components/auth-modal/client.js',
+    uri: '/_components/auth-modal/instances/cmp456',
+    error: {
+      name: 'TypeError',
+      message: \"Cannot read properties of null (reading 'textContent')\",
+      stack: \"TypeError: Cannot read properties of null (reading 'textContent')\\n    at ...\"
+    }
+  }
+]
+```
+
+For implementation details, see
+[`lib/cmd/vite/generate-bootstrap.js`](./lib/cmd/vite/generate-bootstrap.js).
+
 ### Why this matters for bundle size
 
 If `serviceRewritePlugin` is not respected (e.g. a `client.js` file imports
diff --git a/lib/cmd/vite/generate-bootstrap.js b/lib/cmd/vite/generate-bootstrap.js
index 22a0385..a8bb173 100644
--- a/lib/cmd/vite/generate-bootstrap.js
+++ b/lib/cmd/vite/generate-bootstrap.js
@@ -24,6 +24,49 @@ const MOUNT_RUNTIME = `\
 // ── Component mounting (Vite bootstrap) ─────────────────────────────────────
 var CLAY_INSTANCE_KIND = /_components\\/(.+?)(\\/instances|$)/;
 
+// Normalize unknown thrown values into a consistent JSON-friendly payload so
+// mount diagnostics are readable in browser consoles and issue reports.
+function serializeError(error) {
+  if (error == null) return { message: 'Unknown error' };
+  if (typeof error === 'string') return { message: error };
+  if (typeof error !== 'object') return { message: String(error) };
+
+  var payload = {
+    name: error.name || null,
+    message: error.message || String(error),
+    stack: error.stack || null,
+  };
+
+  if (error.code != null) payload.code = error.code;
+  if (error.cause != null) payload.cause = serializeError(error.cause);
+
+  return payload;
+}
+
+// Record one structured error entry for preload/load/mount failures and emit
+// an expandable console group with the full context.
+function reportComponentError(errors, detail) {
+  var payload = {
+    phase: detail.phase,
+    component: detail.component,
+    moduleKey: detail.moduleKey,
+    uri: detail.uri,
+    error: serializeError(detail.error),
+  };
+  var message = payload.error && payload.error.message ? payload.error.message : 'Unknown error';
+  var header = '[clay vite] ' + payload.phase + ' error in ' + payload.component + ': ' + message;
+
+  errors.push(payload);
+
+  if (console.groupCollapsed) {
+    console.groupCollapsed(header);
+    console.error(payload);
+    console.groupEnd();
+  } else {
+    console.error(header, payload);
+  }
+}
+
 function mountComponentModules() {
   performance.mark('clay-components-start');
 
@@ -47,15 +90,38 @@ function mountComponentModules() {
         var preloadKey = 'components/' + pm[1] + '/client.js';
 
         if (_clayClientModules[preloadKey]) {
-          preloads.push(_clayClientModules[preloadKey]());
+          preloads.push({
+            component: pm[1],
+            moduleKey: preloadKey,
+            promise: _clayClientModules[preloadKey](),
+          });
         }
       }
     }
 
-    resolve(Promise.allSettled(preloads));
-  }).then(function() {
+    resolve(preloads);
+  }).then(function(preloads) {
+    var errors = [];
+    var preloadPromises = preloads.map(function(entry) { return entry.promise; });
+
+    return Promise.allSettled(preloadPromises).then(function(results) {
+      results.forEach(function(result, idx) {
+        if (result.status === 'rejected') {
+          reportComponentError(errors, {
+            phase: 'preload',
+            component: preloads[idx].component,
+            moduleKey: preloads[idx].moduleKey,
+            uri: null,
+            error: result.reason,
+          });
+        }
+      });
+      return { errors: errors };
+    });
+  }).then(function(state) {
+    var errors = state.errors;
     var els = Array.from(document.querySelectorAll('[data-uri*="_components/"]'));
-    var mounted = 0, errors = [];
+    var mounted = 0;
 
     return Promise.allSettled(els.map(function(el) {
       var m = CLAY_INSTANCE_KIND.exec(el.dataset.uri);
@@ -72,15 +138,58 @@ function mountComponentModules() {
         .then(function(mod) { return mod.default != null ? mod.default : mod; })
         .then(function(mod) {
           if (typeof mod === 'function') {
-            try { mod(el); mounted++; } catch(e) { errors.push(name + ' (mount): ' + (e && e.message || e)); }
+            try {
+              mod(el);
+              mounted++;
+            } catch (e) {
+              reportComponentError(errors, {
+                phase: 'mount',
+                component: name,
+                moduleKey: key,
+                uri: el.dataset.uri || null,
+                error: e,
+              });
+            }
           } else if (window.DS && typeof window.DS.get === 'function') {
-            try { window.DS.get(name, el); mounted++; } catch(e) { errors.push(name + ': ' + e.message); }
+            try {
+              window.DS.get(name, el);
+              mounted++;
+            } catch (e) {
+              reportComponentError(errors, {
+                phase: 'ds-mount',
+                component: name,
+                moduleKey: key,
+                uri: el.dataset.uri || null,
+                error: e,
+              });
+            }
           }
         })
-        .catch(function(e) { errors.push(name + ' (load): ' + (e && e.message || e)); });
+        .catch(function(e) {
+          reportComponentError(errors, {
+            phase: 'load',
+            component: name,
+            moduleKey: key,
+            uri: el.dataset.uri || null,
+            error: e,
+          });
+        });
     })).then(function() {
       console.debug('[clay vite] mounted ' + mounted + '/' + els.length + ' components');
-      if (errors.length) console.warn('[clay vite] mount errors:', errors);
+      if (errors.length) {
+        var summary = errors.map(function(entry) {
+          return {
+            phase: entry.phase,
+            component: entry.component,
+            moduleKey: entry.moduleKey,
+            uri: entry.uri,
+            message: entry.error && entry.error.message,
+          };
+        });
+        console.warn('[clay vite] mount errors (' + errors.length + ')');
+        if (console.table) console.table(summary);
+        console.error('[clay vite] mount error details', errors);
+      }
     });
   }).finally(function() {
     performance.mark('clay-components-end');
diff --git a/lib/cmd/vite/generators.test.js b/lib/cmd/vite/generators.test.js
index b99a20e..caa3831 100644
--- a/lib/cmd/vite/generators.test.js
+++ b/lib/cmd/vite/generators.test.js
@@ -110,6 +110,8 @@ describe('generate-vite env/bootstrap/kiln generators', () => {
       expect(content).toContain('"components/article/client.js": () => import("../components/article/client.js")');
       expect(content).toContain('"layouts/homepage/client.js": () => import("../layouts/homepage/client.js")');
       expect(content).toContain('fired["auth:init"] = ev.detail;');
+      expect(content).toContain("console.warn('[clay vite] mount errors (' + errors.length + ')');");
+      expect(content).toContain("console.error('[clay vite] mount error details', errors);");
       expect(content).toContain('mountComponentModules().catch(console.error);');
     });