CRATIS-UI-1003 logs a console error for every slot outside an adapter's documented profile

[cratis-stagehand]

With @cratis/components.primereact selected as library, the browser console fills with errors like:

[CRATIS-UI-1003] Renderer resolution requested Core fallback for slot 'dialogs.dialog'.
Remedy: Provide a supported 'dialogs.dialog' renderer declaration or intentionally retain the Core fallback.

unstable_useSlot reports a strictProfileFallback diagnostic whenever a slot resolves to Core while any library layer is mounted (renderer/RendererContext.js), and unstable_logDiagnostic emits it through console.error.

Why that reads as a defect

The adapter documents itself as a nine-slot profile, and the migration guide is explicit that Core keeps Dialog, Dropdown, DatePicker, paginator and table regardless of which adapter is installed. So Core fallback for dialogs.dialog is not a misconfiguration — it is the documented, only-possible outcome of installing the adapter. Reporting it at error severity means an application that has done exactly what the docs say ships a console full of errors, which trains people to ignore the console and buries the diagnostics that are actionable.

The remedy text offers "or intentionally retain the Core fallback" as an alternative, but there is no way to express that intent: rendererFallback: 'core' is already the default and does not silence it, and libraryMode: 'degrade' only affects library-validation diagnostics, not slot fallbacks.

Suggested direction

State the problem rather than the fix, but some options: only report a fallback for slots the selected library claims in profileSlots and stay quiet for slots outside the profile; or lower out-of-profile fallbacks to console.debug/info; or add a way to acknowledge the expected Core set once at the provider.

Found while migrating Cratis/Stagehand to Components 4 with the PrimeReact 11 adapter (Cratis/Stagehand#356).

[cratis-stagehand]

Investigation

Investigation Summary

I have identified the root cause and confirmed the issue with clear evidence:

The Problem

When using @cratis/components.primereact adapter (which documents a 9-slot profile: button, iconButton, textInput, textArea, checkbox, radio, switch, progress, surface), the console fills with errors like:

[CRATIS-UI-1003] Renderer resolution requested Core fallback for slot 'dialogs.dialog'.
Remedy: Provide a supported 'dialogs.dialog' renderer declaration or intentionally retain the Core fallback.

This occurs because Core slots (Dialog, Dropdown, DatePicker, paginator, table) are documented as intentionally Core-only, not part of the adapter's profile.

Root Cause

In RendererContext.tsx, the unstable_useSlot function (lines 228-273) creates and reports a strictProfileFallback diagnostic (CRATIS-UI-1003) for any Core fallback when a library layer is mounted:

const diagnostic =
    result.usedCoreFallback && (context?.layers.length ?? 0) > 0
        ? fallbackDiagnostic(context, slotId)
        : undefined;

The bug: This doesn't distinguish between:

• Slots the adapter doesn't claim (expected Core fallback, documented behavior) → should NOT error
• Slots the adapter does claim but didn't provide (true misconfiguration) → should error

Evidence of Contradiction in Tests

Test A (when_reporting_fallback_diagnostics.tsx:44) expects an error when probing a slot outside the profile.

Test B (when_resolving_slots.tsx:166) explicitly tests "should allow fallback outside a declared profile promise without render side effects" (i.e., no console.error) and expects consoleError.callCount to equal 0.

Test B's name and assertions confirm the documented behavior: slots outside the adapter's profileSlots should fall back silently.

Fix Strategy

Modify unstable_useSlot to:

1. Check if the fallback slot is in the active library's profileSlots
2. Only report the diagnostic if the slot IS in the profile (misconfiguration)
3. Silently use Core fallback if the slot is NOT in the profile (expected behavior)

Files to Change

1. RendererContext.tsx (lines 228-273): Add profile-slot check before creating diagnostic
2. when_reporting_fallback_diagnostics.tsx (lines 44-72): Update test to reflect correct behavior

---

SUGGESTED-MODEL: sonnet

Recommended Implementation Plan

1. Modify RendererContext.tsx unstable_useSlot function:

   • After unstable_resolveSlot() returns with usedCoreFallback: true
   • Check if any context layer exists and if the layer has profileSlots
   • Compare the slotId against the active library's profileSlots
   • Only create the diagnostic if slotId is in profileSlots (promised but not delivered)
   • If slotId is not in profileSlots, silently return the fallback

2. Update test in when_reporting_fallback_diagnostics.tsx:

   • Change the test at line 44 to create a library that claims to support a slot
   • Modify that library's slots to have fidelity: 'unsupported' for that slot (or omit the declaration)
   • Verify the error is still reported (because the adapter promised it but didn't deliver)
   • This aligns the test with the documented behavior

3. Verify existing test in when_resolving_slots.tsx:

   • The test at line 166 ("should allow fallback outside a declared profile promise...") should pass after the fix
   • This test confirms the correct behavior

4. Quality gate verification:

   • Run yarn test to confirm all specs pass
   • Specifically verify both test files pass with corrected logic
   • Build Release configuration to confirm no TypeScript errors

This fix ensures applications following the documented adapter behavior (using Core-only slots) ship without console errors, while still catching genuine misconfiguration when an adapter claims to support a slot but doesn't deliver it.

Suggested model for implementation: opus

---

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