@alfakit/react 0.1.13 → 0.2.0

package/dist/themes.css

@@ -1015,3 +1015,95 @@
   box-shadow: none;
   outline: none;
 }
+
+/* ------------------------------------------------------------------ CMS site design */
+
+/*
+ * Public CMS pages (alfasix/alfakit-cms). **Site design** sets the theme variables on the
+ * document root; these rules apply its fonts and each block's **Style** section
+ * (`data-cms-background`, `data-cms-spacing`, `data-cms-visibility` on
+ * `data-slot="cms-block"`). The page keeps copies of its colours so a coloured block can
+ * swap them for its content.
+ */
+[data-slot='cms-page'] {
+  --cms-primary: var(--primary);
+  --cms-on-primary: var(--primary-foreground);
+  --cms-secondary: var(--secondary);
+  --cms-on-secondary: var(--secondary-foreground);
+  font-family: var(--cms-font-body);
+}
+
+/* In-page links (`#pricing`) stop below the sticky site header. */
+[data-slot='cms-page'] [data-slot='cms-block'][id] {
+  scroll-margin-top: 5rem;
+}
+
+[data-slot='cms-page'] :is(h1, h2, h3, h4, h5, h6) {
+  font-family: var(--cms-font-heading, var(--cms-font-body));
+}
+
+[data-slot='cms-block'][data-cms-background] {
+  background-color: var(--background);
+  color: var(--foreground);
+}
+
+[data-slot='cms-block'][data-cms-background='muted'] {
+  --background: var(--muted);
+}
+
+[data-slot='cms-block'][data-cms-background='primary'],
+[data-slot='cms-block'][data-cms-background='secondary'],
+[data-slot='cms-block'][data-cms-background='dark'] {
+  --muted: color-mix(in oklab, var(--foreground) 10%, var(--background));
+  --muted-foreground: color-mix(in oklab, var(--foreground) 80%, var(--background));
+  --border: color-mix(in oklab, var(--foreground) 22%, var(--background));
+  --card: color-mix(in oklab, var(--foreground) 7%, var(--background));
+  --card-foreground: var(--foreground);
+}
+
+[data-slot='cms-block'][data-cms-background='primary'] {
+  --background: var(--cms-primary);
+  --foreground: var(--cms-on-primary);
+  --primary: var(--cms-on-primary);
+  --primary-foreground: var(--cms-primary);
+}
+
+[data-slot='cms-block'][data-cms-background='secondary'] {
+  --background: var(--cms-secondary);
+  --foreground: var(--cms-on-secondary);
+}
+
+[data-slot='cms-block'][data-cms-background='dark'] {
+  --background: oklch(0.205 0 0);
+  --foreground: oklch(0.985 0 0);
+}
+
+[data-slot='cms-block'][data-cms-spacing='none'] > * {
+  padding-block: 0;
+}
+
+[data-slot='cms-block'][data-cms-spacing='small'] > * {
+  padding-block: 1.5rem;
+}
+
+[data-slot='cms-block'][data-cms-spacing='large'] > * {
+  padding-block: 6rem;
+}
+
+@media (min-width: 640px) {
+  [data-slot='cms-block'][data-cms-spacing='large'] > * {
+    padding-block: 8rem;
+  }
+}
+
+@media (max-width: 767.98px) {
+  [data-slot='cms-block'][data-cms-visibility='desktop'] {
+    display: none;
+  }
+}
+
+@media (min-width: 768px) {
+  [data-slot='cms-block'][data-cms-visibility='mobile'] {
+    display: none;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfakit/react",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "description": "React + shadcn/ui renderer for Alfakit, the Laravel admin panel builder by Alfa Six.",
   "license": "MIT",
   "author": "Alfa Six (https://alfasixbh.com)",
@@ -96,7 +96,7 @@
     "react-day-picker": "^10.0.2",
     "sonner": "^2.0.8",
     "tailwind-merge": "^3.7.0",
-    "@alfakit/core": "0.1.13"
+    "@alfakit/core": "0.2.0"
   },
   "peerDependencies": {
     "@inertiajs/react": "^3.0.0",

package/src/components/cms/blocks.tsx

@@ -1,6 +1,7 @@
 import {
   CMS_FORM_KEY,
   cmsAspectClass,
+  cmsBlockAttributes,
   cmsBlockKey,
   cmsBlocks,
   cmsColumnsClass,
@@ -464,7 +465,12 @@ export function CmsBlocks({
         if (!Component) return null
 
         return (
-          <div key={block.id} id={block.id} data-slot="cms-block" data-cms-block={block.type}>
+          <div
+            key={block.id}
+            {...cmsBlockAttributes(block)}
+            data-slot="cms-block"
+            data-cms-block={block.type}
+          >
             <Component block={block} data={block.data} />
           </div>
         )

package/src/components/cms/head.tsx

@@ -1,11 +1,18 @@
-import { cmsHeadTags, type CmsSeoSchema } from '@alfakit/core'
+import { cmsDesignLinks, cmsHeadTags, type CmsSeoSchema, type CmsSiteDesign } from '@alfakit/core'
 import { Head } from '@inertiajs/react'
 
 /**
- * The page's `<title>`, meta, canonical, `hreflang` and JSON-LD tags, through Inertia's
- * `<Head>` (server-rendered with SSR, updated on every visit).
+ * The page's `<title>`, meta, canonical, `hreflang` and JSON-LD tags, plus the site
+ * design's favicon and fonts, through Inertia's `<Head>` (server-rendered with SSR,
+ * updated on every visit).
  */
-export function CmsHead({ seo }: { seo: CmsSeoSchema | null | undefined }) {
+export function CmsHead({
+  seo,
+  design,
+}: {
+  seo: CmsSeoSchema | null | undefined
+  design?: CmsSiteDesign | null
+}) {
   const tags = cmsHeadTags(seo)
 
   return (
@@ -36,6 +43,14 @@ export function CmsHead({ seo }: { seo: CmsSeoSchema | null | undefined }) {
           hrefLang={link.hreflang}
         />
       ))}
+      {cmsDesignLinks(design).map((link) => (
+        <link
+          key={`design:${link.rel}`}
+          head-key={`cms:design:${link.rel}`}
+          rel={link.rel}
+          href={link.href}
+        />
+      ))}
       {/* Encoded on the server with `<` escaped, so it can't close the element. */}
       {tags.jsonLd && (
         <script head-key="cms:jsonld" type="application/ld+json">

package/src/components/cms/page.tsx

@@ -1,6 +1,7 @@
 import {
   CMS_FOOTER_KEY,
   CMS_HEADER_KEY,
+  cmsDesignCss,
   cmsPayload,
   type CmsPageProps,
   type CmsPayload,
@@ -42,7 +43,16 @@ export function CmsHeader({ cms }: { cms: CmsPayload }) {
           href={cms.site.url}
           className="focus-visible:ring-ring/50 rounded-md text-lg font-semibold tracking-tight outline-none focus-visible:ring-[3px]"
         >
-          {cms.site.name}
+          {cms.site.design?.logo ? (
+            <img
+              src={cms.site.design.logo.url}
+              alt={cms.site.design.logo.alt}
+              data-slot="cms-logo"
+              className="h-9 w-auto max-w-48 object-contain"
+            />
+          ) : (
+            cms.site.name
+          )}
         </a>
         <div className="flex items-center gap-2">
           <CmsNav menu={cms.menus.main}>
@@ -130,6 +140,7 @@ function CmsPageLayout({ cms, children }: { cms: CmsPayload; children?: ReactNod
   const { t } = useCms()
   const header: AnyComponent = registry?.resolve(CMS_HEADER_KEY) ?? CmsHeader
   const footer: AnyComponent = registry?.resolve(CMS_FOOTER_KEY) ?? CmsFooter
+  const designCss = cmsDesignCss(cms.site.design)
 
   return (
     <div
@@ -145,6 +156,10 @@ function CmsPageLayout({ cms, children }: { cms: CmsPayload; children?: ReactNod
       >
         {t('cms.skip_to_content', {}, 'Skip to content')}
       </a>
+      {/* Site design: built on the server from checked values, never contains `<`. */}
+      {designCss && (
+        <style data-slot="cms-design" dangerouslySetInnerHTML={{ __html: designCss }} />
+      )}
       {cms.preview && <PreviewBanner />}
       {createElement(header, { cms })}
       <main
@@ -204,7 +219,7 @@ export function CmsPage({
 
   return (
     <CmsProvider payload={cms} components={components}>
-      <CmsHead seo={cms.page.seo} />
+      <CmsHead seo={cms.page.seo} design={cms.site.design} />
       <CmsPageLayout cms={cms} />
     </CmsProvider>
   )

package/src/components/fields/file-upload.tsx

@@ -147,7 +147,8 @@ export function FileUploadField({ component }: { component: FileUploadSchema })
       const local = pendingFile(file, position)
       setUploading((state) => [...state, local])
 
-      queued.push(limit(() => send(endpoint, file, local)))
+      // Submits wait for queued and running uploads, so saving now doesn't drop the file.
+      queued.push(store.trackUpload(limit(() => send(endpoint, file, local))))
     }
 
     await Promise.all(queued)
@@ -254,7 +255,7 @@ export function FileUploadField({ component }: { component: FileUploadSchema })
 
     const local = pendingFile(file, `edit:${existing.path}`)
     setUploading((state) => [...state, local])
-    await send(endpoint, file, local, existing.path)
+    await store.trackUpload(send(endpoint, file, local, existing.path))
   }
 
   const send = async (endpoint: string, file: File, local: LocalFile, replacing?: string) => {
@@ -596,10 +597,10 @@ export function FileUploadField({ component }: { component: FileUploadSchema })
               </span>
             )}
             {!circle &&
-              (component.acceptedFileTypes || component.maxSize || component.minFiles) && (
+              (component.acceptedFileTypesLabel || component.maxSize || component.minFiles) && (
                 <span className="text-muted-foreground text-xs">
                   {[
-                    component.acceptedFileTypes?.join(', '),
+                    component.acceptedFileTypesLabel,
                     component.maxSize
                       ? `≤ ${fileManagerSize(component.maxSize * 1024, formatter)}`
                       : null,

package/src/components/fields/rich-editor.tsx

@@ -110,7 +110,7 @@ import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } fro
 import { useActionRunner, usePanel, useT } from '../../context'
 import { Icon } from '../../lib/icons'
 import { cn } from '../../lib/utils'
-import { useField } from '../form/form-context'
+import { useField, useOptionalFormStore } from '../form/form-context'
 import { FieldWrapper } from '../schema/field-wrapper'
 import { Button } from '../ui/button'
 import { Separator } from '../ui/separator'
@@ -284,6 +284,7 @@ function RichEditorInput({
 }) {
   const t = useT()
   const panel = usePanel()
+  const formStore = useOptionalFormStore()
   const runner = useActionRunner()
   const { value, setValue, blur, error, id, disabled, readOnly, aria } =
     useField<unknown>(component)
@@ -516,7 +517,11 @@ function RichEditorInput({
 
   const pickImage = () => fileInput.current?.click()
 
-  const uploadImage = async (file: File) => {
+  // Submits wait for the attachment's upload, so saving now doesn't drop the image.
+  const uploadImage = (file: File) =>
+    formStore ? formStore.trackUpload(sendImage(file)) : sendImage(file)
+
+  const sendImage = async (file: File) => {
     if (!panel.endpoints.upload || !editor) return
 
     // The server checks again when the form is saved.

package/src/components/fields/slider.tsx

@@ -101,7 +101,9 @@ export function SliderField({ component }: { component: SliderSchema }) {
   }
 
   return (
-    <FieldWrapper field={component} htmlFor={`${id}-thumb-0`} error={error}>
+    // The wrapper's label, hint and error ids derive from `id`, as `aria` does: a thumb is not
+    // labelable, so one thumb names itself through `aria-labelledby`.
+    <FieldWrapper field={component} htmlFor={id} error={error}>
       <div
         data-slot="slider"
         className={cn(

package/src/components/panel/app-sidebar.tsx

@@ -8,7 +8,7 @@ import {
 } from '@alfakit/core'
 import { Link } from '@inertiajs/react'
 import { ChevronRightIcon } from 'lucide-react'
-import type { ComponentProps, ReactNode } from 'react'
+import { useState, type ComponentProps, type ReactNode } from 'react'
 import { useDirection, usePanel, useT } from '../../context'
 import { extraProps } from '../../lib/attributes'
 import { badgeColorClasses, colorClass } from '../../lib/colors'
@@ -114,12 +114,32 @@ function NavLink({
   )
 }
 
+/**
+ * Open state of a collapsible menu entry: `defaultOpen` at first, and opened again when the
+ * entry becomes active. The sidebar stays mounted across visits, so it keeps what the user
+ * opened or closed, while a page reached from elsewhere still shows its menu entry.
+ */
+function useOpenWhenActive(defaultOpen: boolean, active: boolean) {
+  const [open, setOpen] = useState(defaultOpen)
+  const [wasActive, setWasActive] = useState(active)
+
+  if (active !== wasActive) {
+    setWasActive(active)
+
+    if (active) setOpen(true)
+  }
+
+  return { open, onOpenChange: setOpen }
+}
+
 /** Child items (any depth) with their own badges, new-tab links and nested children. */
 function NavSubItem({ item }: { item: NavigationItemSchema }) {
+  const collapsible = useOpenWhenActive(!!item.active, !!item.active)
+
   if (item.children && item.children.length > 0) {
     return (
       <SidebarMenuSubItem>
-        <Collapsible defaultOpen={item.active} className="group/nav-sub">
+        <Collapsible {...collapsible} className="group/nav-sub">
           <CollapsibleTrigger asChild>
             <SidebarMenuSubButton asChild isActive={item.active}>
               <button type="button" {...extraProps(item.extraAttributes, 'w-full')}>
@@ -156,9 +176,11 @@ function NavSubItem({ item }: { item: NavigationItemSchema }) {
 }
 
 function NavItem({ item }: { item: NavigationItemSchema }) {
+  const collapsible = useOpenWhenActive(!!item.active, !!item.active)
+
   if (item.children && item.children.length > 0) {
     return (
-      <Collapsible asChild defaultOpen={item.active} className="group/collapsible">
+      <Collapsible asChild {...collapsible} className="group/collapsible">
         <SidebarMenuItem>
           <CollapsibleTrigger asChild>
             <SidebarMenuButton
@@ -259,6 +281,8 @@ function NavGroup({ group }: { group: NavigationGroupSchema }) {
   const attributes = extraProps(group.extraSidebarAttributes)
   // A labelled group with an icon collapses into a flyout in the icon-only sidebar.
   const flyout = Boolean(group.label && group.icon)
+  const active = group.items.some((item) => item.active)
+  const collapsible = useOpenWhenActive(!group.collapsed || active, active)
   const content = (
     <SidebarGroupContent className={cn(flyout && 'group-data-[collapsible=icon]:hidden')}>
       <SidebarMenu>
@@ -288,10 +312,7 @@ function NavGroup({ group }: { group: NavigationGroupSchema }) {
   }
 
   return (
-    <Collapsible
-      defaultOpen={!group.collapsed || group.items.some((item) => item.active)}
-      className="group/nav-group"
-    >
+    <Collapsible {...collapsible} className="group/nav-group">
       <SidebarGroup {...attributes}>
         <CollapsibleTrigger asChild>
           <SidebarGroupLabel

package/src/components/panel/global-search.tsx

@@ -133,7 +133,10 @@ export function GlobalSearch({ variant = 'topbar' }: { variant?: 'topbar' | 'sid
           </span>
         )}
         {hydrated && suffix?.type === 'keyBinding' && (
-          <kbd dir="ltr" className="bg-muted hidden rounded px-1 font-mono text-[10px] sm:inline">
+          <kbd
+            dir="ltr"
+            className="bg-muted text-foreground/70 hidden rounded px-1 font-mono text-[10px] sm:inline"
+          >
             {formatKeyBinding(suffix.keyBinding)}
           </kbd>
         )}

package/src/components/panel/shortcut-keys.tsx

@@ -26,7 +26,7 @@ export function ShortcutKeys({ binding, className }: { binding: string; classNam
           )}
           <kbd
             dir="ltr"
-            className="bg-muted text-muted-foreground rounded border px-1.5 font-mono text-[10px] leading-5"
+            className="bg-muted text-foreground/70 rounded border px-1.5 font-mono text-[10px] leading-5"
           >
             {step}
           </kbd>

package/src/components/table/list-tabs.tsx

@@ -69,7 +69,9 @@ export function ListTabs({
               cn(
                 'inline-flex h-[calc(100%-1px)] shrink-0 items-center justify-center gap-1.5 rounded-md border border-transparent px-2.5 py-1 text-sm font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:ring-[3px] focus-visible:outline-none',
                 'focus-visible:border-ring focus-visible:ring-ring/50',
-                active ? 'bg-background text-foreground shadow-sm' : 'hover:text-foreground',
+                active
+                  ? 'bg-background text-foreground shadow-sm'
+                  : 'text-foreground/70 hover:text-foreground',
               ),
             )}
             ref={(element) => {

package/src/components/table/table-views.tsx

@@ -240,7 +240,9 @@ export function TableViews({
               className={cn(
                 'inline-flex h-[calc(100%-1px)] shrink-0 items-center justify-center gap-1.5 rounded-md border border-transparent px-2.5 py-1 text-sm font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:ring-[3px] focus-visible:outline-none',
                 'focus-visible:border-ring focus-visible:ring-ring/50',
-                selected ? 'bg-background text-foreground shadow-sm' : 'hover:text-foreground',
+                selected
+                  ? 'bg-background text-foreground shadow-sm'
+                  : 'text-foreground/70 hover:text-foreground',
               )}
               onClick={() => !selected && visitTableView(table, item?.key ?? null)}
               onKeyDown={(event) => onTabKeyDown(event, index)}

package/src/context.tsx

@@ -12,7 +12,15 @@ import {
   type Translator,
 } from '@alfakit/core'
 import { usePage } from '@inertiajs/react'
-import { createContext, useContext, useMemo, type ComponentType, type ReactNode } from 'react'
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  type ComponentType,
+  type ReactNode,
+} from 'react'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type AnyComponent = ComponentType<any>
@@ -33,6 +41,14 @@ export interface AlfakitContextValue {
    * change). Panels leave it out (a partial reload); components outside panels fetch theirs.
    */
   refresh?: (targets: string[]) => Promise<void>
+  /**
+   * Whether every page is rendered only after the split built-ins and discovered components
+   * it names have loaded, on the server and before hydration (`createAlfakit()` resolves
+   * pages that way). Without it (starter kits, standalone components) those components show
+   * after hydration: a long-lived SSR server keeps code earlier requests loaded, a fresh
+   * browser has none of it, so rendering them early would make the markups differ.
+   */
+  preloadsPageComponents?: boolean
 }
 
 const AlfakitContext = createContext<AlfakitContextValue | null>(null)
@@ -52,6 +68,35 @@ function useOptionalPageProps(): AlfakitPageProps {
   }
 }
 
+/**
+ * The Inertia page URL, or undefined outside an Inertia app. Persistent chrome (the panel
+ * layout stays mounted across visits) closes its phone sheets when it changes.
+ */
+export function useOptionalPageUrl(): string | undefined {
+  try {
+    return usePage().url
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Calls `close` when the user moves to another page. The panel layout persists across
+ * visits, so menus and sheets that used to be reset by remounting close here instead.
+ * Partial reloads (deferred props, polling) keep the URL and leave them open.
+ */
+export function useCloseOnVisit(close: () => void): void {
+  const url = useOptionalPageUrl()
+  const previous = useRef(url)
+
+  useEffect(() => {
+    if (previous.current === url) return
+
+    previous.current = url
+    close()
+  }, [url, close])
+}
+
 /**
  * Outside panels there is no shared `alfakit` prop and no `page` prop: `<AlfakitComponent>`
  * provides both from its payload, and the hooks below read them first.

package/src/create-alfakit.tsx

@@ -50,7 +50,7 @@ import { AlfakitProvider, useAlfakit, type AlfakitContextValue, type AnyComponen
 import { panelLayouts } from './layouts/panel-layouts'
 import { discoverComponents } from './lib/discovery'
 import { preloadIcons } from './lib/icons'
-import { AlfakitPage } from './pages/page'
+import { AlfakitPage, PanelLayoutHost } from './pages/page'
 import { builtInComponents, createDefaultRegistry } from './registry'
 import { claimToaster } from './standalone/toaster-claims'
 
@@ -100,7 +100,10 @@ export function AlfakitRoot({
   return (
     <Direction.Provider dir={direction}>
       <TooltipProvider delayDuration={0}>
-        <SchemaContractGuard panel={panel}>{children}</SchemaContractGuard>
+        {/* The panel layout stays mounted across visits between Alfakit pages. */}
+        <SchemaContractGuard panel={panel}>
+          <PanelLayoutHost>{children}</PanelLayoutHost>
+        </SchemaContractGuard>
         <ActionModals />
         <FlashToasts />
         <RealtimeNotifications />
@@ -187,6 +190,8 @@ export function bootAlfakit(
       registry,
       pages,
       translator,
+      // `resolve` below loads the page's split built-ins and discovered files first.
+      preloadsPageComponents: true,
       // The runner's endpoints are refreshed on every navigation from the shared props.
       actions: new ActionRunner({
         endpoints: { action: '', modal: '' },

package/src/layouts/app-layout.tsx

@@ -6,14 +6,14 @@ import {
   type BreadcrumbSchema,
   type Width,
 } from '@alfakit/core'
-import { createElement, type CSSProperties, type ReactNode } from 'react'
+import { createElement, useCallback, type CSSProperties, type ReactNode } from 'react'
 import { AppSidebar } from '../components/panel/app-sidebar'
 import { BottomNav } from '../components/panel/bottom-nav'
 import { TopbarLocaleSwitcher } from '../components/panel/locale-switcher'
 import { Slot } from '../components/panel/slot'
 import { Topbar } from '../components/panel/topbar'
-import { SidebarInset, SidebarProvider, SidebarTrigger } from '../components/ui/sidebar'
-import { useAlfakitProps, useRegistry } from '../context'
+import { SidebarInset, SidebarProvider, SidebarTrigger, useSidebar } from '../components/ui/sidebar'
+import { useAlfakitProps, useCloseOnVisit, useRegistry } from '../context'
 import { cn } from '../lib/utils'
 import { MAX_WIDTHS } from './max-widths'
 import { TopNavLayout } from './top-nav-layout'
@@ -48,6 +48,18 @@ export function MobileTopbar() {
   )
 }
 
+/**
+ * The layout stays mounted across visits: the phone sidebar sheet closes when the user
+ * moves to another page.
+ */
+function CloseMobileSidebarOnVisit() {
+  const { setOpenMobile } = useSidebar()
+
+  useCloseOnVisit(useCallback(() => setOpenMobile(false), [setOpenMobile]))
+
+  return null
+}
+
 export function AppLayout({ children, breadcrumbs, maxContentWidth }: AppLayoutProps) {
   const props = useAlfakitProps()
   const registry = useRegistry()
@@ -73,6 +85,7 @@ export function AppLayout({ children, breadcrumbs, maxContentWidth }: AppLayoutP
       defaultOpen={sidebarDefaultOpen(props.alfakitSidebarOpen, layout)}
       style={sidebarWidthStyle(props.alfakit) as CSSProperties | undefined}
     >
+      <CloseMobileSidebarOnVisit />
       <Slot name="body.start" />
       <Slot name="layout.start" />
       {createElement(Sidebar)}

package/src/lib/discovery.tsx

@@ -4,29 +4,44 @@ import {
   type DiscoveryModules,
   type DiscoveryOptions,
 } from '@alfakit/core'
-import { createElement, useEffect, useState } from 'react'
-import type { AnyComponent } from '../context'
+import { createElement, useEffect, useState, useSyncExternalStore } from 'react'
+import { useOptionalAlfakit, type AnyComponent } from '../context'
+
+const subscribe = () => () => {}
 
 /**
  * A discovered component: rendered straight away once its code has loaded (the pages that
  * use it preload it, see `ComponentDiscovery.preloadFor()`), else as soon as it arrives
  * (through state, not `<Suspense>`, whose reveal React throttles by up to 300 ms).
  * Each mount keeps the path it started with, so loading never remounts a field.
+ *
+ * Where pages are not preloaded (starter kits, standalone components), the server render
+ * and hydration leave it out even when its code is loaded: a long-lived SSR server keeps
+ * what earlier requests loaded, a fresh browser has none of it (OM-B06).
  */
 export function discoveredComponent(entry: DiscoveredEntry<AnyComponent>): AnyComponent {
   function Discovered(props: Record<string, unknown>) {
+    const preloaded = useOptionalAlfakit()?.preloadsPageComponents === true
+    // False on the server and while hydrating, true for every later render and mount.
+    const hydrated = useSyncExternalStore(
+      subscribe,
+      () => true,
+      () => false,
+    )
+    const ready = preloaded || hydrated
     const [state, setState] = useState<{ component?: AnyComponent; error?: unknown }>(() => ({
-      component: entry.current,
+      component: ready ? entry.current : undefined,
     }))
+    const component = state.component ?? (ready ? entry.current : undefined)
 
     useEffect(() => {
-      if (state.component) return
+      if (component) return
 
       let active = true
 
       entry.load().then(
-        (component) => {
-          if (active) setState({ component })
+        (loaded) => {
+          if (active) setState({ component: loaded })
         },
         (error: unknown) => {
           if (active) setState({ error: error ?? new Error(`Failed to load ${entry.key}`) })
@@ -36,11 +51,11 @@ export function discoveredComponent(entry: DiscoveredEntry<AnyComponent>): AnyCo
       return () => {
         active = false
       }
-    }, [state.component])
+    }, [component])
 
     if (state.error !== undefined) throw state.error
 
-    return state.component ? createElement(state.component, props) : null
+    return component ? createElement(component, props) : null
   }
 
   Discovered.displayName = `Discovered(${entry.key})`