PrimeReact adapter's missing-license attestation white-screens the whole application

[cratis-direct]

@cratis/components.primereact's PrimeReactAdapterProvider throws CRATIS-UI-1005 when rendererSetup['cratis-primereact.license-configured'] is anything but true:

const PrimeReactAdapterProvider = ({ children, setup }) => {
    const primeReact = useContext(PrimeReactContext);
    if (!primeReact || setup[licenseConfiguredAttestation] !== true) {
        throw new unstable_AdapterError({ code: unstable_adapterErrorCodes.missingLicenseKey, ... });
    }
    return children;
};

That provider is mounted by RendererContext around every child of CratisComponentsProvider, so the throw takes down the entire application tree, not the adapted controls.

Why that is a problem in practice

An application that wires the adapter honestly - rendererSetup: { 'cratis-primereact.license-configured': Boolean(licenseKey) } - renders nothing at all for any developer without a key. Before Components 4, a missing PrimeUI key produced a console warning and PrimeReact's own "Invalid PrimeUI License" badge; it never blocked rendering. So adopting the adapter turns a soft, visible degradation into a hard white screen, on exactly the machines least likely to have the secret.

The only ways out are both unsatisfying: attest true unconditionally, which defeats the point of the attestation and is a false statement about what the outer provider received; or, as we did, select library only when a key is present - which silently gives local development a different renderer, and therefore a different look, from production.

Suggested direction

Stating the problem rather than prescribing: the nine adapted slots have a working Core implementation, so a missing attestation could degrade to Core with a loud one-time console error instead of throwing - which is what rendererFallback and libraryMode: 'degrade' already suggest as the vocabulary for this. Whatever the mechanism, an unlicensed developer machine rendering the app with Cratis-owned buttons seems strictly better than rendering nothing.

Found while migrating Cratis/Stagehand to Components 4 (Cratis/Stagehand#356).

[cratis-direct]

Investigation

Investigation Complete — Summary and Recommendation

Based on my investigation, here is what I found:

Root Cause: The PrimeReactAdapterProvider in /workspace/Adapters/PrimeReact/src/index.tsx (lines 75-82) throws CRATIS-UI-1005 when setup['cratis-primereact.license-configured'] is not true. Since this provider wraps every child of CratisComponentsProvider, the thrown error immediately white-screens the entire application.

Current Behavior:

• Missing license → immediate throw → entire app fails
• Developers without a PrimeUI license (esp. in local dev) get a white screen instead of a working app with Core components

Intended Behavior (per the issue):

• Missing license → console warning (once) → app renders with Core fallback components
• Uses the existing rendererFallback and libraryMode: 'degrade' vocabulary

How Degradation Works:
The Components renderer has a built-in graceful fallback mechanism:

1. When a slot is used via unstable_useSlot(), it checks if the renderer can provide that slot
2. If not, it falls back to Core automatically (when rendererFallback='core', the default)
3. The framework logs diagnostics when in libraryMode='degrade'

The Fix:
Modify PrimeReactAdapterProvider to:

1. Remove the throw (lines 76-82)
2. Log a one-time console warning when license attestation is false
3. Return children without the provider context (or return children as-is)
4. Let each individual slot use the Core fallback via unstable_useSlot() when PrimeReact is unavailable

This aligns with how the framework's libraryMode: 'degrade' is designed to work.

---

SUGGESTED-MODEL: sonnet

Plan:

1. Modify PrimeReactAdapterProvider — Remove the throw, add a one-time warning log when license is not configured, return children (slot resolution will handle Core fallback)
2. Test the fix locally — Verify that without a license attestation, the app renders with Core components instead of white-screening
3. Verify with libraryMode='degrade' — Confirm that in degrade mode, the warning is logged once and the app still works
4. Verify with libraryMode='strict' — Confirm that in strict mode (default), the adapter still reports a diagnostic appropriately
5. Ensure backward compatibility — Apps with a valid license should work exactly as before

Suggested model for implementation: opus

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.