@igstack/app-catalog-frontend-core 6.6.0 → 6.7.0

package/src/modules/appCatalog/ui/detail/AppDetails.tsx

@@ -31,6 +31,7 @@ import { formatRelativeTime } from '../../utils/formatRelativeTime'
 import { TierVariantsSection } from '../components/TierVariantsSection'
 import { SubResourcesSection } from '../components/SubResourcesSection'
 import { getChildResources } from '../../utils/resolveHelpers'
+import { ResourceDetailAccessActions } from '~/modules/extensions'
 import { FeedbackSection } from './FeedbackSection'
 import { displayUrl } from '~/modules/appCatalog/utils/displayUrl'
 import { accessTabLabel } from '~/modules/appCatalog/utils/accessTabLabel'
@@ -116,11 +117,9 @@ function AppScreenshot({ app }: { app: Resource }) {
 export function AppDetails({
   app,
   onAppClick,
-  onClosePanel,
 }: {
   app: Resource
   onAppClick?: (app: Resource) => void
-  onClosePanel: () => void
 }) {
   const [isGalleryOpen, setIsGalleryOpen] = React.useState(false)
   const [galleryInitialIndex, setGalleryInitialIndex] = React.useState(0)
@@ -175,6 +174,31 @@ export function AppDetails({
     [allResources, app.slug],
   )
 
+  // `app` is whatever resource the card shows, a nested one included, so the
+  // parent has to be looked up rather than assumed absent. A plugin uses its
+  // presence to tell a sub-resource view from a top-level one.
+  const parent = React.useMemo(
+    () =>
+      app.parentSlug
+        ? allResources.find((r) => r.slug === app.parentSlug)
+        : undefined,
+    [allResources, app.parentSlug],
+  )
+
+  // What a plugin slot in the band receives. Memoised so a plugin that
+  // memoises on its props is not defeated by a new object every render.
+  const accessActionsCtx = React.useMemo(
+    () => ({
+      resource: app,
+      parent,
+      subResources: parent
+        ? getChildResources(allResources, parent.slug)
+        : children,
+      user: user ? { email: user.email, isAdmin } : null,
+    }),
+    [app, parent, allResources, children, user, isAdmin],
+  )
+
   // Enter: open screenshot gallery
   useHotkeys(
     'enter',
@@ -198,21 +222,6 @@ export function AppDetails({
     [app, isGalleryOpen],
   )
 
-  // Esc: close the details panel (only when gallery is NOT open)
-  //
-  // From inside a text field too: the Quick Jump field holds the caret from the
-  // moment the card opens, so the default "ignore form tags" left the card with
-  // no keyboard way out. A field that wants Esc for itself stops the event —
-  // InlineEditableField does, so Esc there cancels the edit and nothing more.
-  useHotkeys(
-    'escape',
-    () => {
-      onClosePanel()
-    },
-    { enabled: !isGalleryOpen, enableOnFormTags: ['input'] },
-    [isGalleryOpen, onClosePanel],
-  )
-
   const handleScreenshotClick = (index: number) => {
     setGalleryInitialIndex(index)
     setIsGalleryOpen(true)
@@ -346,7 +355,9 @@ export function AppDetails({
                     <SubResourcesSection
                       subResources={children}
                       parentSlug={app.slug}
+                      parent={app}
                       initialSearch={filterState.searchValue}
+                      childrenLabel={app.childrenLabel}
                     />
                   </div>
                 )}
@@ -650,15 +661,24 @@ export function AppDetails({
             card to find. Up here it is present on every tab, which is the whole
             reason the band does not scroll away.
             `mr-10` keeps it clear of the dialog's own close button at top-right. */}
-        <Button
-          type="button"
-          size="sm"
-          variant="outline"
-          className="ml-auto mr-10"
-          onClick={() => setComposeRequests((n) => n + 1)}
-        >
-          ✎ Suggest a change
-        </Button>
+        {/* Plugin actions sit beside "Suggest a change", sharing its reasoning:
+            the band is mounted on every tab and never scrolls away. A slot in a
+            tab panel would be invisible until a second click, and one inside
+            SubResourceDetailPanel's `hasAnyAccess` gate would vanish for exactly
+            the resources that need help most.
+            Renders nothing when no plugin contributes, so the band keeps its
+            current shape in the open-source build. */}
+        <div className="ml-auto mr-10 flex items-center gap-2">
+          <ResourceDetailAccessActions {...accessActionsCtx} />
+          <Button
+            type="button"
+            size="sm"
+            variant="outline"
+            onClick={() => setComposeRequests((n) => n + 1)}
+          >
+            ✎ Suggest a change
+          </Button>
+        </div>
       </div>
 
       {app.nicknames && app.nicknames.length > 0 && (

package/src/modules/appCatalog/ui/detail/DetailTabs.tsx

@@ -116,6 +116,26 @@ export function DetailTabs({
     setUserChose(true)
     setUrlTab(requestTab)
   }, [requestTab, requestNonce, setUrlTab])
+  /**
+   * Releasing the force must not move the view.
+   *
+   * Arriving with `?sub=` forces the sub-resources tab, but only through
+   * `forcedTab` — the tab's own state is still the default. Clearing the
+   * selection drops `?sub=`, the force goes with it, and the strip fell back to
+   * that stale default: the reader was moved to Overview while looking at the
+   * table they had just cleared a filter on. So when the force is released
+   * before the user picked anything, the forced tab becomes the real choice.
+   *
+   * Adjusted during render rather than in an effect, the pattern React
+   * documents for responding to a prop change: an effect would paint one frame
+   * of Overview first, mounting that panel only to tear it down again.
+   */
+  const [lastForced, setLastForced] = React.useState(forcedTab)
+  if (forcedTab !== lastForced) {
+    setLastForced(forcedTab)
+    if (lastForced && !forcedTab && !userChose) setUrlTab(lastForced)
+  }
+
   const asked = userChose || !forcedTab ? urlTab : forcedTab
   const requested = RETIRED[asked] ?? asked
   const activeId = ids.includes(requested) ? requested : (ids[0] ?? '')

package/src/modules/appCatalog/ui/pages/AppCatalogPage.tsx

@@ -68,6 +68,22 @@ export function AppCatalogPage({
     [resources],
   )
 
+  /**
+   * What the grid actually shows, memoized because its IDENTITY matters.
+   *
+   * Filtering inline in the JSX produced a new array on every render, and the
+   * grid keys four `useMemo`s off this prop (the slug index, "new this week",
+   * the browse list and its area grouping). A fresh identity invalidated all
+   * four on every keystroke — recomputed even while searching, when the
+   * discovery spine they feed is not on screen. The search box lives in a
+   * context above this component, so every keystroke re-renders here.
+   */
+  const visibleRootResources = useMemo(
+    () =>
+      rootResources.filter((a) => filterState.showDeprecated || !a.deprecated),
+    [rootResources, filterState.showDeprecated],
+  )
+
   // Dev-only skew warning: data arrived (resources > 0) but nothing is top-level
   // (rootResources === 0). That fingerprints a frontend/backend-core version skew
   // or a stale service worker — NOT a normal empty search/filter (those still have
@@ -187,9 +203,7 @@ export function AppCatalogPage({
     // against the bottom edge or under the floating support bubble.
     <div className="flex-1 min-h-0 overflow-y-auto [scrollbar-gutter:stable] pb-24">
       <AppCatalogGrid
-        apps={rootResources.filter(
-          (a) => filterState.showDeprecated || !a.deprecated,
-        )}
+        apps={visibleRootResources}
         // All resources incl. children — so search matches sub-resources
         // (e.g. a cloud account) and surfaces their parent.
         allResources={resources}

package/src/modules/auth/AuthContext.tsx

@@ -131,3 +131,18 @@ export function useUser() {
   const { user } = useAuth()
   return user
 }
+
+/**
+ * The current user, or null when there is no `AuthProvider` above.
+ *
+ * `useUser()` throws without a provider, which is correct for UI that only ever
+ * renders inside the app but wrong for anything a test may mount bare. Several
+ * components are rendered bare on purpose (`AppDetailPanel`, `AppCatalogGrid`),
+ * so assembling a plugin slot payload with `useUser()` there turns every one of
+ * those tests red — "useAuth must be used within AuthProvider".
+ *
+ * Signed-out and no-provider are the same answer for a slot payload: null.
+ */
+export function useOptionalUser() {
+  return use(AuthContext)?.user ?? null
+}

package/src/modules/auth/index.ts

@@ -4,6 +4,7 @@ export {
   useAuth,
   useIsAuthenticated,
   useUser,
+  useOptionalUser,
 } from './AuthContext'
 export { ProtectedContent, withProtection } from './ProtectedContent'
 export { LoginPage } from './ui/LoginPage'

package/src/modules/dismiss/DismissStack.tsx

@@ -0,0 +1,224 @@
+import { createContext, use, useEffect, useMemo, useRef } from 'react'
+
+/**
+ * One Escape key, one answer: dismiss the layer on top.
+ *
+ * Before this existed, Escape was handled in six independent places, and each
+ * one had to know about the others to avoid double-firing — the detail card
+ * bound Escape only `enabled: !isGalleryOpen`, the gallery installed its own
+ * capture-phase listener specifically to beat Radix to the event, and the
+ * screenshot dialog cancelled Radix's own Escape by reading the gallery's
+ * fullscreen state through a ref. Every new overlay had to learn that dance,
+ * and getting it wrong stayed invisible until someone pressed Escape in the
+ * wrong order. It was wrong: a dialog opened over the card had no say, so
+ * Escape closed the card out from under it and navigated away.
+ *
+ * A layer now says only "I am dismissable, and this element is me". The stack
+ * decides who Escape belongs to, and no layer needs to know another exists.
+ *
+ * "On top" is DOCUMENT ORDER, the last enabled layer in the document. Two
+ * cheaper keys were tried first and both broke:
+ *
+ * - Registration order. React runs a child's effects before its parent's, so
+ *   an overlay nested inside another registers FIRST and the container looks
+ *   newer: Escape in the screenshot viewer closed the card under it.
+ * - Activation time. On a cold deep link the dialog's route resolves before
+ *   the catalog arrives, so the card it sits over mounts LATER and looks
+ *   newer: Escape closed the card first, and the card took focus back off the
+ *   dialog's first field.
+ *
+ * Document order has neither problem because it is what "on top" means on
+ * screen: a portal appends to the end of `<body>`, a child route renders after
+ * its parent's page, and a nested layer is a descendant — and a descendant
+ * follows its ancestor in document order. None of it depends on when anything
+ * mounted.
+ *
+ * `useDismissable` works with or without a provider above it, on purpose. A
+ * hook that silently did nothing outside a provider would be the same class of
+ * bug this module exists to delete — every render site, including tests and
+ * stories, would have to remember a wrapper, and forgetting it would look like
+ * working code with dead Escape handling. So an app-wide stack is the default
+ * and `DismissStackProvider` is only for scoping.
+ */
+
+interface DismissEntry {
+  /** The layer's root element; its position in the document is its rank. */
+  layer: { readonly current: HTMLElement | null }
+  /** Called when Escape belongs to this layer. */
+  onDismiss: () => void
+  /**
+   * A layer can stay registered and opt out — a collapsed panel, a closed
+   * popover. Skipped when choosing the top rather than unregistering.
+   */
+  enabled: boolean
+}
+
+export interface DismissStackApi {
+  /** Adds an entry and returns its unregister function. */
+  register: (entry: DismissEntry) => () => void
+  /** Dismisses the top layer; reports whether there was one. */
+  dismissTop: () => boolean
+  /**
+   * The top layer's element, or null when nothing is open. For a layer that
+   * takes focus on mount: it should only do so while it is on top, or it
+   * steals the caret from whatever was opened over it.
+   */
+  topElement: () => HTMLElement | null
+}
+
+function isAfter(a: HTMLElement, b: HTMLElement): boolean {
+  // A descendant reports FOLLOWING as well as CONTAINED_BY, so this one test
+  // covers both "rendered later" and "nested inside".
+  return (b.compareDocumentPosition(a) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0
+}
+
+function createStack(): DismissStackApi {
+  const entries: DismissEntry[] = []
+
+  const top = (): DismissEntry | undefined => {
+    let best: DismissEntry | undefined
+    for (const entry of entries) {
+      const el = entry.layer.current
+      // Not in the document yet, or already gone: not something on screen.
+      if (!entry.enabled || !el?.isConnected) continue
+      const bestEl = best?.layer.current
+      if (!bestEl || isAfter(el, bestEl)) best = entry
+    }
+    return best
+  }
+
+  const dismissTop = () => {
+    const entry = top()
+    if (!entry) return false
+    entry.onDismiss()
+    return true
+  }
+
+  const topElement = () => top()?.layer.current ?? null
+
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (event.key !== 'Escape') return
+    // Something closer to the event already dealt with it — a text field
+    // cancelling an edit, say. Honoured rather than overridden: the element the
+    // user is typing in is more specific than any layer containing it.
+    //
+    // This check is the reason the listener below is on the BUBBLE phase. In
+    // capture it would run before every component handler, so `defaultPrevented`
+    // would always be false and a field could never keep Escape for itself.
+    if (event.defaultPrevented) return
+    if (!dismissTop()) return
+    // Claim it, so a handler further out does not also act.
+    event.preventDefault()
+    event.stopPropagation()
+  }
+
+  const register = (entry: DismissEntry) => {
+    if (entries.length === 0) {
+      // Bubble, on the document: every component handler and React's own
+      // delegated handlers run first, so the innermost thing that wants Escape
+      // gets it. Radix is the one exception — it listens with `capture: true`,
+      // so it runs BEFORE this. `DialogContent` bridges that by asking the
+      // stack from inside Radix's own escape callback.
+      document.addEventListener('keydown', onKeyDown)
+    }
+    entries.push(entry)
+    return () => {
+      const i = entries.indexOf(entry)
+      if (i !== -1) entries.splice(i, 1)
+      if (entries.length === 0) {
+        document.removeEventListener('keydown', onKeyDown)
+        return
+      }
+      // When a layer closes, the caret it held goes with it and lands on
+      // <body>, where the next Tab walks whatever is behind every overlay and
+      // Escape still works only because this listener is on the document.
+      // Hand it to the layer that is now on top. Only from <body>: if
+      // something already restored focus — Radix returns it to the trigger —
+      // that choice is more specific than this one and stands.
+      queueMicrotask(() => {
+        if (document.activeElement && document.activeElement !== document.body)
+          return
+        topElement()?.focus()
+      })
+    }
+  }
+
+  return { register, dismissTop, topElement }
+}
+
+/**
+ * The app-wide stack, used whenever no provider scopes one.
+ *
+ * Module-level so two sibling overlays coordinate even if neither sits under a
+ * provider — which is the whole point. Created lazily so importing this module
+ * never touches `document`, keeping it safe in a non-DOM environment.
+ */
+let appStack: DismissStackApi | null = null
+function getAppStack(): DismissStackApi {
+  appStack ??= createStack()
+  return appStack
+}
+
+const DismissStackContext = createContext<DismissStackApi | null>(null)
+
+/**
+ * Scopes a stack to a subtree.
+ *
+ * Only needed when overlays inside must not compete with overlays outside —
+ * two independently mounted apps on one page, for instance. The app does not
+ * need it for ordinary nesting; the default stack already handles that.
+ */
+export function DismissStackProvider({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const api = useMemo(() => createStack(), [])
+  return <DismissStackContext value={api}>{children}</DismissStackContext>
+}
+
+/**
+ * Declare this layer dismissable by Escape.
+ *
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null)
+ * useDismissable(ref, onClose)                      // always dismissable
+ * useDismissable(ref, close, { enabled: isOpen })   // only while open
+ * return <div ref={ref} role="dialog">…</div>
+ * ```
+ *
+ * `ref` is the layer's root element, and it is required rather than optional
+ * because it IS the ordering: the last enabled layer in the document owns
+ * Escape. Call the hook once per layer, unconditionally; nothing else
+ * coordinates with any other layer, and adding one above an existing layer
+ * needs no change to it.
+ */
+export function useDismissable(
+  layer: { readonly current: HTMLElement | null },
+  onDismiss: () => void,
+  { enabled = true }: { enabled?: boolean } = {},
+): void {
+  const scoped = use(DismissStackContext)
+  const stack = scoped ?? getAppStack()
+
+  // A stable entry whose fields are refreshed in place. Handing `register` a
+  // new object whenever the callback identity changed would churn the stack on
+  // every render for no benefit.
+  const entryRef = useRef<DismissEntry>({ layer, onDismiss, enabled })
+  useEffect(() => {
+    entryRef.current.layer = layer
+    entryRef.current.onDismiss = onDismiss
+    entryRef.current.enabled = enabled
+  }, [layer, onDismiss, enabled])
+
+  useEffect(() => stack.register(entryRef.current), [stack])
+}
+
+/**
+ * The stack itself, for a component that owns its own key handling or focus
+ * and wants stack ordering instead of inventing its own.
+ */
+export function useDismissStack(): DismissStackApi {
+  const scoped = use(DismissStackContext)
+  return scoped ?? getAppStack()
+}

package/src/modules/extensions/ExtensionsContext.tsx

@@ -0,0 +1,36 @@
+import { createContext, use } from 'react'
+import type { ReactNode } from 'react'
+import type { PluginRegistration } from './types'
+
+const ExtensionsInternalContext = createContext<
+  readonly PluginRegistration[] | undefined
+>(undefined)
+
+interface ExtensionsContextProps {
+  children: ReactNode
+  value?: readonly PluginRegistration[]
+}
+
+export function ExtensionsContext({ children, value }: ExtensionsContextProps) {
+  return (
+    <ExtensionsInternalContext value={value}>
+      {children}
+    </ExtensionsInternalContext>
+  )
+}
+
+/**
+ * Registered plugins, or an empty list.
+ *
+ * Empty is the open-source default and has to stay a first-class state: every
+ * slot renders nothing and every wrapper passes its children through, so the UI
+ * is identical to one with no slots at all. Slots are additive — a slot must
+ * never be the only route to something the core itself needs.
+ */
+export function useExtensions(): readonly PluginRegistration[] {
+  return use(ExtensionsInternalContext) ?? EMPTY
+}
+
+// Module-level constant: a fresh `[]` per call would be a new identity every
+// render and defeat memoisation in anything downstream of it.
+const EMPTY: readonly PluginRegistration[] = []

package/src/modules/extensions/factories.ts

@@ -0,0 +1,19 @@
+import { makeSlot, makeWrapper } from './makeSlot'
+
+/**
+ * Binds one feature's slot spec, so each slot names itself exactly once and the
+ * name is checked against that feature's own spec.
+ *
+ *   const mkSlot = slotFactory<AppCatalogSlots>()
+ *   export const ResourceDetailAccessActions = mkSlot('resourceDetailAccessActions')
+ *                                               // ^ typo here is a compile error
+ */
+export function slotFactory<TSpec>() {
+  return <TName extends keyof TSpec & string>(name: TName) =>
+    makeSlot<TSpec[TName]>(name)
+}
+
+export function wrapperFactory<TSpec>() {
+  return <TName extends keyof TSpec & string>(name: TName) =>
+    makeWrapper<TSpec[TName]>(name)
+}

package/src/modules/extensions/features/resourceDetail.ts

@@ -0,0 +1,74 @@
+import type { Resource } from '@igstack/app-catalog-backend-core'
+import { slotFactory, wrapperFactory } from '../factories'
+import type { PluginUser } from '../types'
+
+/**
+ * Leaf slots on the resource detail card.
+ *
+ * Payloads are additive-only. Adding a field is invisible to existing plugins;
+ * renaming or removing one breaks them at compile time on their next core bump,
+ * which is the intended moment for that to surface.
+ */
+export interface ResourceDetailSlots {
+  /**
+   * Actions on the detail card's header band.
+   *
+   * The band and not a tab panel: tab panels mount only while active and
+   * Overview is first, so a slot inside a tab is invisible until a second click.
+   */
+  resourceDetailAccessActions: {
+    /** The resource on screen — a top-level app OR one of its sub-resources. */
+    resource: Resource
+    /** Present only on a sub-resource view. Its absence is how a plugin tells the two apart. */
+    parent?: Resource
+    /** Children of `parent ?? resource`: the family's sub-resources. */
+    subResources: Resource[]
+    user: PluginUser | null
+  }
+
+  /**
+   * One cell per row of the sub-resources table, in a column of its own.
+   *
+   * Called once per rendered row, which is the opposite shape to
+   * `resourceDetailAccessActions` — that one is called once and handed the whole
+   * list. Use this when the action belongs to a single child.
+   *
+   * Two things to know before filling it. The table renders EVERY row with no
+   * virtualisation, so a contribution here is mounted as many times as the
+   * family has children (hundreds, in a large catalog) — keep the cell cheap and
+   * defer anything expensive until it is interacted with. And the column only
+   * appears when a plugin actually fills it, so a build with no plugin renders
+   * the table exactly as before.
+   */
+  resourceSubResourceRowActions: {
+    /** The child this row is showing. */
+    resource: Resource
+    /** The entry the row hangs off. Always present here, unlike the header slot. */
+    parent: Resource
+    user: PluginUser | null
+  }
+}
+
+/**
+ * Wrappers on the resource detail card.
+ *
+ * `resourceDetailProvider` is mounted inside the panel's `key={shownSlug}`
+ * subtree, so anything a plugin provides here is scoped to the resource on
+ * screen and is discarded when the card navigates. That is what lets two slots
+ * share per-resource state without the plugin writing any cleanup.
+ */
+export interface ResourceDetailWrappers {
+  resourceDetailProvider: {
+    resource: Resource
+    parent?: Resource
+  }
+}
+
+const mkSlot = slotFactory<ResourceDetailSlots>()
+const mkWrapper = wrapperFactory<ResourceDetailWrappers>()
+
+export const ResourceDetailAccessActions = mkSlot('resourceDetailAccessActions')
+export const ResourceSubResourceRowActions = mkSlot(
+  'resourceSubResourceRowActions',
+)
+export const ResourceDetailProvider = mkWrapper('resourceDetailProvider')

package/src/modules/extensions/index.ts

@@ -0,0 +1,121 @@
+import { useMemo } from 'react'
+import type { ReactNode } from 'react'
+// Relative, not `~`: this file is on the published entry's graph and therefore
+// in every consumer's program, and `~` is the CORE's alias — a consumer only
+// resolves it if it has mapped it, which the example app has not.
+import { useOptionalUser } from '../auth/AuthContext'
+import type {
+  ResourceDetailSlots,
+  ResourceDetailWrappers,
+} from './features/resourceDetail'
+import type { AssertDisjoint, PluginUser } from './types'
+
+import { useExtensions } from './ExtensionsContext'
+
+export { ExtensionsContext, useExtensions } from './ExtensionsContext'
+export { slotFactory, wrapperFactory } from './factories'
+export { makeSlot, makeWrapper } from './makeSlot'
+export type { PluginUser, PluginRegistration } from './types'
+export type { AssertDisjoint } from './types'
+export {
+  ResourceDetailAccessActions,
+  ResourceSubResourceRowActions,
+  ResourceDetailProvider,
+} from './features/resourceDetail'
+export type {
+  ResourceDetailSlots,
+  ResourceDetailWrappers,
+} from './features/resourceDetail'
+
+/**
+ * Every leaf slot in the core, composed from the per-feature specs.
+ *
+ * Adding a feature means a new `features/<name>.ts` plus one member here and one
+ * line in the guard below. No existing feature file is touched.
+ */
+export type SlotSpec = ResourceDetailSlots
+
+/** Every wrapper slot in the core. */
+export type WrapperSpec = ResourceDetailWrappers
+
+// Guard: with a second feature this becomes
+// `AssertDisjoint<ResourceDetailSlots, ServiceDeskSlots>` and fails with the
+// duplicated id spelled out in the error. With one feature it is trivially true,
+// and is kept so the next feature inherits the check rather than inventing it.
+const _slotIdsAreDisjoint: AssertDisjoint<SlotSpec, Record<never, never>> = true
+void _slotIdsAreDisjoint
+
+/**
+ * A plugin's leaf-slot handlers. Each receives exactly its slot's payload.
+ *
+ * Registering an unknown slot, or reading a field the slot does not pass, is a
+ * compile error — which is the whole point of composing `SlotSpec` rather than
+ * typing handlers as `(props: unknown)`.
+ */
+export type PluginSlots = {
+  [N in keyof SlotSpec]?: (props: SlotSpec[N]) => ReactNode
+}
+
+/** A plugin's wrapper handlers. `children` is injected by the core. */
+export type PluginWrappers = {
+  [N in keyof WrapperSpec]?: (
+    props: WrapperSpec[N] & { children: ReactNode },
+  ) => ReactNode
+}
+
+/**
+ * One deployment-specific feature's contribution to the core's UI.
+ *
+ * Passed to `<App extensions={[...]} />` as an array, not a keyed map: a map
+ * holds one value per key, so a second plugin at the same slot would silently
+ * replace the first and two wrappers around one subtree would be impossible.
+ *
+ * The array must be a module-level constant. The core iterates it in render
+ * order, so rebuilding it per render would change hook call order inside the
+ * plugins and violate the rules of hooks.
+ */
+export interface AcPlugin {
+  /** Identity, used in error reports and test assertions. */
+  name: string
+  slots?: PluginSlots
+  wrappers?: PluginWrappers
+}
+
+/**
+ * Whether any registered plugin fills this slot.
+ *
+ * For the cases where rendering the slot is not enough and the core has to
+ * change its own layout around it — a table column, say, which would otherwise
+ * be an empty column with a header and no cells in every build that registers
+ * nothing. Rendering an empty slot costs nothing; reserving space for one is
+ * what this is for.
+ *
+ * Use it ONLY for layout. A slot must never be the only route to something the
+ * core itself needs, so branching behaviour on a plugin's presence is a design
+ * smell even where branching layout is not.
+ */
+export function useSlotFilled(slot: keyof SlotSpec): boolean {
+  return useExtensions().some((plugin) => Boolean(plugin.slots?.[slot]))
+}
+
+/**
+ * The signed-in user, reduced to what slots are given.
+ *
+ * One place, so two slots cannot disagree about the shape — and deliberately a
+ * projection rather than the real user object: the core's `User` is free to grow
+ * fields, and handing a plugin the whole thing would make every one of them part
+ * of the published slot contract.
+ *
+ * Returns `null` with no `AuthProvider` above it. The detail card renders inside
+ * the catalog panel, which some suites mount outside the provider, and throwing
+ * there would make a plugin's presence break unrelated tests.
+ */
+export function usePluginUser(): PluginUser | null {
+  const user = useOptionalUser()
+  return useMemo(
+    // `?? false`, because admin is a capability: absent must read as "not an
+    // admin", never as undefined leaking into a plugin's own check.
+    () => (user ? { email: user.email, isAdmin: user.isAdmin ?? false } : null),
+    [user],
+  )
+}