@crossworks/share-ui 0.232.9 → 0.232.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/share-ui",
-  "version": "0.232.9",
+  "version": "0.232.10",
   "description": "The server-rendered share surface — the /s/<token> presenters, view-payload contract, mini-app sandbox, and the few primitives they need. Lives in MANTLE (the server renders these), published for jackdaw to consume; may depend only on @mantle/{client-types,content-core} (the jackdaw-repo-split boundary).",
   "exports": {
     "./app-presenter": "./src/app-presenter.tsx",
@@ -32,8 +32,8 @@
     "./styles/app.css": "./styles/app.css"
   },
   "dependencies": {
-    "@mantle/client-types": "npm:@crossworks/client-types@0.232.9",
-    "@mantle/content-core": "npm:@crossworks/content-core@0.232.9",
+    "@mantle/client-types": "npm:@crossworks/client-types@0.232.10",
+    "@mantle/content-core": "npm:@crossworks/content-core@0.232.10",
     "@radix-ui/react-label": "^2.1.12",
     "@radix-ui/react-slot": "^1.3.0",
     "class-variance-authority": "^0.7.1",

package/src/app-frame-html.test.ts

@@ -0,0 +1,51 @@
+/**
+ * The frame document is the only place that can witness a MODULE-LEVEL failure
+ * — a link error or a module-scope throw happens before any component exists,
+ * so the kit's ErrorBoundary cannot catch it. Without the reporter the parent
+ * has no signal at all and can only time out with a causeless message, which is
+ * exactly what a wrong `@host` import cost in the field.
+ */
+import { describe, expect, it } from 'vitest';
+import { buildAppFrameHtml } from './app-frame-html';
+
+const frame = (bundleCode: string) =>
+  buildAppFrameHtml({
+    bundleCode,
+    appCss: '',
+    importMapJson: '{"imports":{}}',
+    cls: '',
+    colorTheme: null,
+    viewport: true,
+  });
+
+describe('buildAppFrameHtml — error reporting', () => {
+  it('installs the reporter BEFORE the app module, or it cannot catch boot', () => {
+    const html = frame('console.log(1)');
+    const reporter = html.indexOf("addEventListener('error'");
+    const appModule = html.indexOf('<script type="module">');
+    expect(reporter).toBeGreaterThan(-1);
+    expect(appModule).toBeGreaterThan(-1);
+    expect(reporter).toBeLessThan(appModule);
+  });
+
+  it('posts the bridge-shaped error message the parent already understands', () => {
+    const html = frame('console.log(1)');
+    expect(html).toContain("kind:'error'");
+    expect(html).toContain('v:1');
+    expect(html).toContain('window.parent.postMessage');
+  });
+
+  it('listens in the capture phase — a module script error does not bubble', () => {
+    expect(frame('x')).toMatch(/addEventListener\('error'[\s\S]*?\}, true\)/);
+  });
+
+  it('also covers an unhandled rejection at module scope', () => {
+    expect(frame('x')).toContain("addEventListener('unhandledrejection'");
+  });
+
+  it('still emits the app bundle and the import map', () => {
+    const html = frame('const marker = 42;');
+    expect(html).toContain('const marker = 42;');
+    expect(html).toContain('<script type="importmap">{"imports":{}}</script>');
+  });
+});

package/src/app-frame-html.ts

@@ -129,6 +129,48 @@ function attr(v: string): string {
   return v.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
 }
 
+/**
+ * Error reporter, installed BEFORE the app module so it can see the app fail
+ * during boot.
+ *
+ * A module-level failure — a link error like `does not provide an export named
+ * 'default'`, or a throw at module scope — happens before any component
+ * renders, so the kit's ErrorBoundary cannot exist yet, let alone catch it.
+ * Nothing was reported, the app never posted `ready`, and the parent could only
+ * sit out its 10s watchdog, retry once, and show a causeless "couldn't load the
+ * app" some twenty seconds later — the same blank wall for a typo, a dead
+ * chunk, or a real crash. Now the parent has the actual reason in milliseconds.
+ *
+ * `error` on window catches both cases: module link/parse errors surface there
+ * even though no user code ran. Capture phase, because a module script's error
+ * event does not bubble.
+ *
+ * It deliberately does NOT try to decide whether the app had already booted —
+ * `ready` goes to the (cross-origin) parent, so this document never sees it,
+ * and `window.parent.postMessage` cannot be wrapped to eavesdrop. The PARENT
+ * already tracks that (`everReadyRef` in app-sandbox) and is the right place to
+ * classify: pre-ready error = load failure, post-ready = runtime hiccup. So
+ * this reports faithfully and lets the parent judge.
+ */
+const ERROR_REPORTER = `(function(){
+  var last = '';
+  function report(msg){
+    var text = String(msg || 'the app failed to start');
+    if (text === last) return;   // a repeating error must not become a message loop
+    last = text;
+    try { window.parent.postMessage({ v:1, kind:'error', message: text }, '*'); } catch (_) {}
+  }
+  window.addEventListener('error', function(e){
+    // Subresource load failures (img/link) target an element, not window, and
+    // are not app failures — ignore them.
+    if (e && e.target && e.target !== window && e.target.tagName) return;
+    report((e && (e.message || (e.error && e.error.message))) || 'the app failed to start');
+  }, true);
+  window.addEventListener('unhandledrejection', function(e){
+    report((e && e.reason && (e.reason.message || e.reason)) || 'the app failed to start');
+  });
+})();`;
+
 export function buildAppFrameHtml(opts: {
   /** The app's built module bundle (esbuild output; esbuild escapes any
    *  `</script` inside string literals, so inlining it is safe). */
@@ -194,6 +236,7 @@ body{overflow:auto}`
 </head>
 <body class="bg-background text-foreground">
 <div id="root"></div>
+<script>${ERROR_REPORTER}</script>
 <script type="module">${opts.bundleCode}</script>
 <script>${INSPECTOR}</script>
 </body>

package/src/app-sandbox.tsx

@@ -100,6 +100,9 @@ export function AppSandbox({
   const apiBase = apiBaseOverride ?? (shareToken ? `/s/${shareToken}` : `/api/apps/${appId}`);
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const [status, setStatus] = useState<Status>('loading');
+  /** Why the app failed, when the frame could tell us. Shown under the
+   *  generic line so a load failure is diagnosable without the console. */
+  const [failReason, setFailReason] = useState<string | null>(null);
   const [height, setHeight] = useState(320);
   // The frame URL (ticket included), held in state so the iframe is RENDERED
   // with its src (keyed per attempt) — the element is created carrying the
@@ -239,10 +242,17 @@ export function AppSandbox({
       }
       if (m.kind === 'error') {
         cbRef.current.onError?.(m.message);
-        // An error BEFORE the app ever became ready is a mount/boot crash (the
-        // kit's ErrorBoundary posts it synchronously during the first render,
-        // ahead of the ready signal) — a load failure, not a runtime hiccup.
-        if (!everReadyRef.current) cbRef.current.onLoadFailure?.();
+        // An error BEFORE the app ever became ready is a mount/boot failure —
+        // the kit's ErrorBoundary for a render crash, or the frame's own
+        // reporter for a module-level link/parse error it could never catch.
+        // Either way the app is not coming up, so fail NOW with the reason
+        // instead of leaving the user on a spinner until the watchdog expires
+        // and then saying nothing useful.
+        if (!everReadyRef.current) {
+          setFailReason(m.message);
+          setStatus('error');
+          cbRef.current.onLoadFailure?.();
+        }
         return;
       }
       if (m.kind === 'select') {
@@ -299,6 +309,7 @@ export function AppSandbox({
   useEffect(() => {
     let cancelled = false;
     setStatus('loading');
+    setFailReason(null);
     setFrameSrc(null);
     everReadyRef.current = false;
     doFetch(`${apiBase}/frame-ticket`, { method: 'POST' })
@@ -358,7 +369,12 @@ export function AppSandbox({
         <div
           className={`flex items-center justify-center p-6 text-center text-sm text-destructive-ink ${isViewport ? 'h-full' : 'h-40'}`}
         >
-          {isViewport ? 'Couldn’t load the app.' : 'Couldn’t load the app preview.'}
+          <div>
+            <div>{isViewport ? 'Couldn’t load the app.' : 'Couldn’t load the app preview.'}</div>
+            {failReason && (
+              <div className="mt-1 font-mono text-xs break-words opacity-80">{failReason}</div>
+            )}
+          </div>
         </div>
       )}
       {frameSrc !== null && (