OpalShaderShell

The web app has three auth-adjacent surfaces:

All three are thin aliases over OpalShaderShell — apps/web/src/components/app-auth/opal-shader-shell.tsx. The shell exists because writing three independent layouts was the original approach and it left the brand mark broken on two of them.

What the shell bundles

<OpalShaderShell>
  <YourAuthStepComponent />
</OpalShaderShell>

…internally expands to:

<TodayStaticBackground variant='auth' />
<BeaconProvider>
  <OpalNarrativeMarkPoseProvider>
    <main className='relative mx-auto max-w-150 ...'>
      {children}
    </main>
    <OpalNarrativeMarkSlot />
  </OpalNarrativeMarkPoseProvider>
</BeaconProvider>

The pieces and what each does:

The brand-mark trap

The <OpalNarrativeMark /> placeholders that step components mount are pure geometry. They reserve layout footprint (a fixed-size box where the mark should go) and register their position into a beacon store. They do not paint anything by themselves.

If you mount the placeholder without BeaconProvider + OpalNarrativeMarkSlot in a parent, the slot stays empty and the Today mark never renders. The layout looks right; the mark just doesn't appear.

This is exactly what happened to LoginShell and friends pre-shell — they were one-off auth shells that mounted their background directly without the beacon plumbing. The result was three auth pages with blank spots where the brand mark should be.

The shell brings the missing pieces in one place.

When to use it

For any new auth-adjacent page: mount it via OpalShaderShell. Mounting the shared background directly is wrong (you'd have to re-import all the beacon plumbing). Wrapping a step component in a custom shell is also wrong.

// In a new page.tsx under (auth)/ or (oauth)/
import { OpalShaderShell } from '@/components/app-auth/opal-shader-shell'
import { MyNewAuthStep } from '@/components/app-auth/my-new-auth-step'

export default function Page() {
  return (
    <OpalShaderShell>
      <MyNewAuthStep />
    </OpalShaderShell>
  )
}

Test mocks

Unit tests for auth / OAuth pages stub @todayai-labs/opal-ui with passthrough fragments for BeaconProvider, OpalNarrativeMarkPoseProvider, OpalNarrativeMarkSlot, plus OpalLoadingOrbs testid stubs. The mock setup is in per-test vi.mock(...) calls.

When you add a new Opal primitive that gets mounted by an auth-page shell, extend the mocks or the test file fails with:

Error: No "<Name>" export is defined on the "@todayai-labs/opal-ui" mock

That's a familiar error — it just means a real-component import is hitting the mock surface that hasn't grown to cover it yet.

Related

• Auth interaction architecture — what the three surfaces do in the OAuth dance
• Better-Auth quirks — the client-side request injection that fires from these pages
• Workspace → Design system — what @todayai-labs/opal-ui exports and how the placeholders relate to the rest of the design system