AutoFrame: stylesheet-load warning is unactionable — include the URL, and surface CSP-blocked fails distinctly

[QuirkyTurtle94]

Description

AutoFrame mirrors the parent document's <link rel="stylesheet"> nodes into its iframe. When a mirrored link fires onerror (e.g. the iframe's CSP blocks a cross-origin stylesheet, the URL 404s, the CDN is down), Puck logs a single warning:

AutoFrame couldn't load a stylesheet

The message has no URL, no error detail, and no differentiation between causes. If the parent document has several stylesheets, there's no way to tell which one failed, so the warning is unactionable — it fires on every editor mount and there's no clear path to resolution.

Environment

• Puck version: 0.21.1 (@puckeditor/core)
• Browser version: Firefox 134, Chrome 135 (both desktop) — warning is identical, Firefox surfaces it more prominently
• Additional environment info: React 19, Next.js 16 App Router, TypeScript

Steps to reproduce

1. Render <Puck /> in a page where the parent document contains at least one stylesheet the iframe can't successfully load. The simplest repro is an intentionally unreachable href:

import { Puck } from "@measured/puck";

const config = { components: {} };
const data = { content: [], root: {} };

const Editor = () => {
  return (
    <>
      <link rel="stylesheet" href="https://example.invalid/missing.css" />
      <Puck config={config} data={data} />
    </>
  );
};

2. Open the browser's developer console.
3. Observe the warning on every mount of the editor.

What happens

The console prints AutoFrame couldn't load a stylesheet with no URL and no indication of the failure mode, so the developer cannot identify which stylesheet failed or why. The warning repeats for every subsequent mount.

The relevant code lives in packages/core's AutoFrame stylesheet mirroring (in the published v0.21.1 bundle, dist/chunk-EBISZQTK.mjs:5666):

mirror.onerror = () => {
  console.warn(`AutoFrame couldn't load a stylesheet`);
  stylesLoaded = stylesLoaded + 1;
  if (stylesLoaded >= elements.length) {
    onStylesLoaded();
  }
};

What I expect to happen

The warning should include the stylesheet's href so developers can identify the failing resource, and briefly reference common causes (CSP, non-2xx status, network) so the next debugging step is obvious. Something along the lines of:

mirror.onerror = () => {
  const href = mirror instanceof HTMLLinkElement ? mirror.href : undefined;
  console.warn(
    `AutoFrame couldn't load a stylesheet${href ? `: ${href}` : ""}. ` +
    `This can happen if the parent document's stylesheet is blocked by the iframe's CSP, ` +
    `returns a non-2xx status, or fails to reach the network.`
  );
  // ...unchanged
};

Non-breaking and keeps existing behaviour for all other call-sites. Happy to open a PR with the above (or a variant you prefer — e.g. gating the warning behind the existing debug prop, or exposing an onStylesheetError callback so apps can route these how they like).

Additional Media

N/A — pure console output, code samples inline above.