@spree/dashboard-core 0.1.0

package/src/lib/permissions.ts

@@ -0,0 +1,55 @@
+/**
+ * CanCanCan subject class names — use these constants instead of raw strings
+ * to avoid typos in permission checks.
+ *
+ * Matches the Ruby class names serialized by the /api/v3/admin/me endpoint.
+ */
+export const Subject = {
+  All: 'all',
+  Product: 'Spree::Product',
+  Variant: 'Spree::Variant',
+  Order: 'Spree::Order',
+  Customer: 'Spree::User',
+  CustomerGroup: 'Spree::CustomerGroup',
+  AdminUser: 'Spree::AdminUser',
+  ApiKey: 'Spree::ApiKey',
+  AllowedOrigin: 'Spree::AllowedOrigin',
+  Store: 'Spree::Store',
+  Channel: 'Spree::Channel',
+  // Categories are Spree::Category < Spree::Taxon; abilities are published under
+  // the Spree::Taxon subject, so the value stays 'Spree::Taxon' while the key
+  // reads as the user-facing resource name.
+  Category: 'Spree::Taxon',
+  OptionType: 'Spree::OptionType',
+  OptionValue: 'Spree::OptionValue',
+  TaxCategory: 'Spree::TaxCategory',
+  CustomFieldDefinition: 'Spree::MetafieldDefinition',
+  PaymentMethod: 'Spree::PaymentMethod',
+  ShippingMethod: 'Spree::ShippingMethod',
+  StockLocation: 'Spree::StockLocation',
+  StockItem: 'Spree::StockItem',
+  StockTransfer: 'Spree::StockTransfer',
+  PriceList: 'Spree::PriceList',
+  PriceRule: 'Spree::PriceRule',
+  Promotion: 'Spree::Promotion',
+  PromotionAction: 'Spree::PromotionAction',
+  PromotionRule: 'Spree::PromotionRule',
+  GiftCard: 'Spree::GiftCard',
+  Market: 'Spree::Market',
+  WebhookEndpoint: 'Spree::WebhookEndpoint',
+  WebhookDelivery: 'Spree::WebhookDelivery',
+  Wishlist: 'Spree::Wishlist',
+} as const
+
+export type SubjectName = (typeof Subject)[keyof typeof Subject] | string
+
+/** CanCanCan standard actions */
+export const Action = {
+  Manage: 'manage',
+  Read: 'read',
+  Create: 'create',
+  Update: 'update',
+  Destroy: 'destroy',
+} as const
+
+export type ActionName = (typeof Action)[keyof typeof Action] | string

package/src/lib/query-client.ts

@@ -0,0 +1,11 @@
+import { QueryClient } from '@tanstack/react-query'
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60,
+      retry: 1,
+      refetchOnWindowFocus: false,
+    },
+  },
+})

package/src/lib/query-keys.ts

@@ -0,0 +1,69 @@
+import type { QueryKey } from '@tanstack/react-query'
+import { useCallback } from 'react'
+import { useStore } from '../providers/store-provider'
+
+/**
+ * Canonical TanStack query-key shape for every dashboard resource:
+ *
+ *     [resource, storeId, ...rest]
+ *
+ * Use `useResourceKey` (the hook) from inside React components to build
+ * store-scoped keys — it reads `storeId` from `<StoreProvider>` so callers
+ * never spell it themselves:
+ *
+ *     useQuery({ queryKey: useResourceKey('channels', id), ... })
+ *
+ * The bare `resourceKey()` helper is the same builder without the storeId
+ * dependency — keep it for non-hook contexts (tests, build-time defaults).
+ *
+ * Lists: `useResourceKey('channels')`
+ * Singletons: `useResourceKey('channels', id)`
+ * Nested: `useResourceKey('products', productId, 'variants')`
+ *
+ * For invalidation inside `useResourceMutation`, the storeId is auto-injected
+ * — pass the logical key without it:
+ *
+ *     invalidate: [['channels'], ['channels', id]]
+ */
+export function resourceKey(resource: string, ...rest: ReadonlyArray<unknown>): QueryKey {
+  return [resource, ...rest]
+}
+
+/**
+ * Hook variant of `resourceKey` that auto-injects the current `storeId` from
+ * `<StoreProvider>`. The default way to build query keys in dashboard hooks.
+ */
+export function useResourceKey(resource: string, ...rest: ReadonlyArray<unknown>): QueryKey {
+  const { storeId } = useStore()
+  return [resource, storeId, ...rest]
+}
+
+/**
+ * Returns a stable closure that builds store-scoped query keys. Use this when
+ * the key parts (typically an id) are only known later — e.g. inside a
+ * mutation's `onSuccess` where `variables.id` is per-call.
+ *
+ *     const buildKey = useResourceKeyBuilder()
+ *     return useResourceMutation({
+ *       onSuccess: (_data, id) =>
+ *         queryClient.removeQueries({ queryKey: buildKey('channels', id) }),
+ *     })
+ */
+export function useResourceKeyBuilder() {
+  const { storeId } = useStore()
+  return useCallback(
+    (resource: string, ...rest: ReadonlyArray<unknown>): QueryKey => [resource, storeId, ...rest],
+    [storeId],
+  )
+}
+
+/**
+ * Inject `storeId` at position 1 of a query key, leaving the resource name at
+ * position 0 and any further scope after it. Idempotent — if the storeId is
+ * already at position 1, returns the input unchanged.
+ */
+export function withStoreScope(key: QueryKey, storeId: string): QueryKey {
+  if (!Array.isArray(key) || key.length === 0) return key
+  if (key[1] === storeId) return key
+  return [key[0], storeId, ...key.slice(1)]
+}

package/src/lib/route-registry.ts

@@ -0,0 +1,158 @@
+import type { ComponentType } from 'react'
+import { useSyncExternalStore } from 'react'
+import type { SubjectName } from './permissions'
+
+/**
+ * Dashboard route contributed by a plugin. Mounted under the dashboard's
+ * `/_authenticated/$storeId/_plugins/$` catch-all, which reads this registry
+ * at render time and dispatches based on the splat path.
+ *
+ * Path patterns use TanStack-Router-style param tokens (`$brandId`) inside the
+ * plugin's namespace. The dashboard strips the `/$storeId/` prefix before
+ * matching, so a plugin pattern of `/brands/$brandId` matches the URL
+ * `/store_xyz/brands/br_abc123` with `params: { brandId: 'br_abc123' }`.
+ */
+export interface RouteEntry {
+  /**
+   * Stable identifier — used for register/remove/update and as the React key.
+   * Mirrors the slug a plugin would use in its `nav.add({ key })` call so the
+   * sidebar entry and route stay paired.
+   */
+  key: string
+  /**
+   * Path pattern relative to `/$storeId`. Examples: `/brands`,
+   * `/brands/$brandId`, `/wishlists/$wishlistId/items`.
+   * Must start with `/`. Do NOT include the `/$storeId` prefix; the dashboard
+   * adds it at render time.
+   */
+  path: string
+  /**
+   * The component to render. Receives:
+   * - `params`: extracted path params (e.g. matching `/brands/$brandId`
+   *   against `/brands/br_abc` yields `{ brandId: 'br_abc' }`)
+   * - `storeId`: the current store — every plugin route is implicitly scoped
+   *   under `/$storeId/...`
+   * - `searchParams`: the URL search-state object from TanStack Router. Use
+   *   this with `<ResourceTable searchParams={searchParams} ... />` so
+   *   filter/sort/pagination round-trip through the URL.
+   */
+  component: ComponentType<{
+    params: Record<string, string>
+    storeId: string
+    searchParams: Record<string, unknown>
+  }>
+  /**
+   * Optional CanCanCan subject required to view the route. The catch-all
+   * renderer checks `permissions.can('read', subject)` and renders a 403
+   * fallback when denied. Omit for routes that don't need permission gating.
+   */
+  subject?: SubjectName
+}
+
+const entries: RouteEntry[] = []
+const listeners = new Set<() => void>()
+
+function notify() {
+  for (const l of listeners) l()
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+function getSnapshot(): readonly RouteEntry[] {
+  return entries
+}
+
+interface RouteMutator {
+  /** Register a route. Throws if `key` is already registered. */
+  add(entry: RouteEntry): void
+  /** Remove a route by key. No-op when missing. */
+  remove(key: string): void
+}
+
+export const pluginRoutes: RouteMutator = {
+  add(entry) {
+    if (entries.some((e) => e.key === entry.key)) {
+      throw new Error(`Plugin route "${entry.key}" already registered.`)
+    }
+    if (!entry.path.startsWith('/')) {
+      throw new Error(`Plugin route "${entry.key}" path must start with "/", got "${entry.path}".`)
+    }
+    entries.push(entry)
+    notify()
+  },
+  remove(key) {
+    const i = entries.findIndex((e) => e.key === key)
+    if (i === -1) return
+    entries.splice(i, 1)
+    notify()
+  },
+}
+
+/**
+ * Subscribe to plugin route updates. Returns the full list of registered
+ * routes; the catch-all renderer matches against this on every navigation.
+ */
+export function usePluginRoutes(): readonly RouteEntry[] {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+/**
+ * Match a URL splat (the bit after `/$storeId/`) against the registered
+ * routes. Returns the matched entry plus the extracted path params, or
+ * `null` if nothing matched.
+ *
+ * Path patterns support TanStack-style `$param` tokens. A pattern segment
+ * of `$brandId` matches any non-empty URL segment and binds it to
+ * `params.brandId`.
+ *
+ * More-specific patterns win regardless of registration order: `/brands/new`
+ * beats `/brands/$brandId` for the URL `/brands/new` because it has fewer
+ * dynamic segments.
+ */
+export function matchPluginRoute(
+  splat: string,
+  routes: readonly RouteEntry[],
+): { entry: RouteEntry; params: Record<string, string> } | null {
+  // Normalize: strip leading slash, drop empty trailing segments.
+  const urlSegments = splat.replace(/^\/+/, '').split('/').filter(Boolean)
+  const bySpecificity = [...routes].sort(
+    (a, b) => countDynamicSegments(a.path) - countDynamicSegments(b.path),
+  )
+  for (const entry of bySpecificity) {
+    const patternSegments = entry.path.replace(/^\/+/, '').split('/').filter(Boolean)
+    if (patternSegments.length !== urlSegments.length) continue
+
+    const params: Record<string, string> = {}
+    let matched = true
+    for (let i = 0; i < patternSegments.length; i++) {
+      const p = patternSegments[i]
+      const u = urlSegments[i]
+      if (p.startsWith('$')) {
+        params[p.slice(1)] = u
+      } else if (p !== u) {
+        matched = false
+        break
+      }
+    }
+    if (matched) return { entry, params }
+  }
+  return null
+}
+
+function countDynamicSegments(path: string): number {
+  return path
+    .replace(/^\/+/, '')
+    .split('/')
+    .filter((segment) => segment.startsWith('$')).length
+}
+
+/** Test-only: clear the registry. */
+export function __resetPluginRoutes(): void {
+  entries.length = 0
+  notify()
+}

package/src/lib/search-registry.ts

@@ -0,0 +1,129 @@
+import type { ReactNode } from 'react'
+import { useSyncExternalStore } from 'react'
+import type { SubjectName } from './permissions'
+
+/**
+ * Registry for the command-palette global resource search. Mirrors
+ * `nav-registry.ts`: a module-singleton populated at app boot by side-effect
+ * modules (see `@/search/default` in the dashboard app), read reactively via
+ * `useSearchEntries`.
+ *
+ * Each entry teaches the palette how to search one resource type: how to fetch
+ * matches, how to render a result row, and where a row navigates. Adding a new
+ * searchable resource is one `searchRegistry.add(...)` call — no edits to the
+ * palette component or the search hook. Plugins extend search the same way they
+ * extend the nav.
+ *
+ * The result type is erased at the registry boundary (`unknown`): the palette
+ * never inspects a result directly, it only hands each one back to the entry's
+ * own `renderRow`/`getRoute`/`getKey`, which are typed against the resource.
+ * Use `defineSearchEntry` to keep that wiring type-safe at the call site.
+ */
+
+export interface SearchResultRow {
+  /** cmdk value — must be unique across the whole list; prefix with the entry key. */
+  value: string
+  /** Row contents rendered inside the `CommandItem`. */
+  content: ReactNode
+}
+
+export interface SearchEntry<T = unknown> {
+  /** Stable identifier — register/remove key, React key, and result-value prefix. */
+  key: string
+  /** i18n key for the group heading (resolved with `t` at render time). */
+  headingKey: string
+  /** CanCanCan subject gating both the query and the rendered group. Omit for always-on. */
+  subject?: SubjectName
+  /**
+   * Lower numbers render first. Built-ins use 100/200/300… so plugins can slot
+   * between them. Also orders the parallel queries, purely cosmetically.
+   */
+  position?: number
+  /**
+   * Fetch up to `limit` matches for `query`. Returns the raw resource records;
+   * the palette passes each back through this entry's `renderRow`/`getRoute`.
+   */
+  fetch: (query: string, limit: number) => Promise<T[]>
+  /** Stable React key for a single result (typically the prefixed `id`). */
+  getKey: (item: T) => string
+  /** Render one result row's inner content (icon/thumbnail + label + badges). */
+  renderRow: (item: T) => ReactNode
+  /** Resolve the destination for a clicked result, given the active store. */
+  getRoute: (item: T, storeId: string) => { to: string }
+}
+
+interface SearchMutator {
+  /** Register an entry. Throws if the key is already registered. */
+  add<T>(entry: SearchEntry<T>): void
+  /** Remove an entry by key. No-op when missing. */
+  remove(key: string): void
+  /** Patch an existing entry. Throws if the key is missing. */
+  update<T>(key: string, patch: Partial<Omit<SearchEntry<T>, 'key'>>): void
+}
+
+const entries: SearchEntry[] = []
+const listeners = new Set<() => void>()
+let snapshotCache: SearchEntry[] | null = null
+
+function notify() {
+  snapshotCache = null
+  for (const l of listeners) l()
+}
+
+export const searchRegistry: SearchMutator = {
+  add(entry) {
+    if (entries.some((e) => e.key === entry.key)) {
+      throw new Error(
+        `Search entry "${entry.key}" already registered. Use searchRegistry.update().`,
+      )
+    }
+    entries.push(entry as SearchEntry)
+    notify()
+  },
+  remove(key) {
+    const i = entries.findIndex((e) => e.key === key)
+    if (i === -1) return
+    entries.splice(i, 1)
+    notify()
+  },
+  update(key, patch) {
+    const e = entries.find((x) => x.key === key)
+    if (!e) throw new Error(`Search entry "${key}" not found.`)
+    Object.assign(e, patch)
+    notify()
+  },
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+function getSnapshot(): SearchEntry[] {
+  if (!snapshotCache) {
+    snapshotCache = [...entries].sort((a, b) => (a.position ?? 100) - (b.position ?? 100))
+  }
+  return snapshotCache
+}
+
+/** Reactively read the sorted search entries. Re-renders on registry mutation. */
+export function useSearchEntries(): SearchEntry[] {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+/**
+ * Identity helper that infers `T` from `fetch`/`getKey`/`renderRow`/`getRoute`
+ * so the callbacks are typed against the resource at the registration site,
+ * while the registry stores the erased `SearchEntry`.
+ */
+export function defineSearchEntry<T>(entry: SearchEntry<T>): SearchEntry<T> {
+  return entry
+}
+
+/** Test-only: clear the registry. */
+export function __resetSearchRegistry(): void {
+  entries.length = 0
+  notify()
+}

package/src/lib/settings-nav-registry.ts

@@ -0,0 +1,158 @@
+import type { LucideIcon } from 'lucide-react'
+import { useSyncExternalStore } from 'react'
+import type { SubjectName } from './permissions'
+
+/**
+ * Registry for the settings sub-shell sidebar. Mirrors `nav-registry.ts` but
+ * adds a `group` key so entries cluster under labelled section headers
+ * (Store · Localization · Team & Access · Developer …).
+ *
+ * Plugins extend the settings nav by importing `settingsNav` and calling
+ * `settingsNav.add(...)` from a side-effect module loaded at app boot.
+ */
+
+export interface SettingsNavEntry {
+  /** Stable identifier — used for register/remove/update and as the React key. */
+  key: string
+  /**
+   * Visible label. Either `label` (literal) or `labelKey` (i18n key) must be
+   * set; built-in entries use `labelKey` so the sidebar re-renders on
+   * language change. Plugins can use either.
+   */
+  label?: string
+  /** i18n key passed to `t(...)` at render time. Takes precedence over `label`. */
+  labelKey?: string
+  /**
+   * Path template, prefixed with `/$storeId/settings` at render time. Pass paths
+   * like `'/general'` or `'/staff'`, NOT `/store_abc/settings/general`. The
+   * leading slash is required.
+   */
+  path: string
+  /** Icon shown next to the label. */
+  icon?: LucideIcon
+  /** Group identifier — entries with the same group cluster under one header. */
+  group: string
+  /** Position within the group. Lower numbers render first. Defaults to 100. */
+  position?: number
+  /** CanCanCan subject required to see this item. Omit for always-visible. */
+  subject?: SubjectName
+  /** When true, the page is disabled in the sidebar with a "Soon" badge. */
+  comingSoon?: boolean
+}
+
+export interface SettingsNavGroup {
+  /** Group identifier referenced by entries. */
+  key: string
+  /** Visible header label. Mirrors `SettingsNavEntry.label` — pair with `labelKey` when localising. */
+  label?: string
+  /** i18n key passed to `t(...)` at render time. Takes precedence over `label`. */
+  labelKey?: string
+  /** Group ordering. Lower numbers render first. Defaults to 100. */
+  position?: number
+}
+
+interface SettingsNavMutator {
+  /** Register an entry. Throws if the key is already registered. */
+  add(entry: SettingsNavEntry): void
+  /** Remove an entry by key. No-op when missing. */
+  remove(key: string): void
+  /** Patch an existing entry. Throws if the key is missing. */
+  update(key: string, patch: Partial<Omit<SettingsNavEntry, 'key'>>): void
+  /** Register a group. Throws if the key is already registered. */
+  addGroup(group: SettingsNavGroup): void
+}
+
+const entries: SettingsNavEntry[] = []
+const groups: SettingsNavGroup[] = []
+const listeners = new Set<() => void>()
+let snapshotCache: SettingsNavSnapshot | null = null
+
+export interface SettingsNavSnapshot {
+  /** Groups, sorted by `position`, each with their entries (also sorted). */
+  groups: Array<{ group: SettingsNavGroup; entries: SettingsNavEntry[] }>
+  /** Flat list of every entry, sorted by group position then entry position. */
+  all: SettingsNavEntry[]
+}
+
+function notify() {
+  snapshotCache = null
+  for (const l of listeners) l()
+}
+
+export const settingsNav: SettingsNavMutator = {
+  add(entry) {
+    if (!entry.label && !entry.labelKey) {
+      throw new Error(`Settings nav entry "${entry.key}" must define either "label" or "labelKey".`)
+    }
+    if (entries.some((e) => e.key === entry.key)) {
+      throw new Error(`Settings nav entry "${entry.key}" already registered.`)
+    }
+    entries.push(entry)
+    notify()
+  },
+  remove(key) {
+    const i = entries.findIndex((e) => e.key === key)
+    if (i === -1) return
+    entries.splice(i, 1)
+    notify()
+  },
+  update(key, patch) {
+    const e = entries.find((x) => x.key === key)
+    if (!e) throw new Error(`Settings nav entry "${key}" not found.`)
+    Object.assign(e, patch)
+    // Re-validate the merged entry — the patch could remove both label fields.
+    if (!e.label && !e.labelKey) {
+      throw new Error(`Settings nav entry "${e.key}" must define either "label" or "labelKey".`)
+    }
+    notify()
+  },
+  addGroup(group) {
+    if (!group.label && !group.labelKey) {
+      throw new Error(`Settings nav group "${group.key}" must define either "label" or "labelKey".`)
+    }
+    if (groups.some((g) => g.key === group.key)) {
+      throw new Error(`Settings nav group "${group.key}" already registered.`)
+    }
+    groups.push(group)
+    notify()
+  },
+}
+
+function buildSnapshot(): SettingsNavSnapshot {
+  const sortedGroups = [...groups].sort((a, b) => (a.position ?? 100) - (b.position ?? 100))
+  const grouped = sortedGroups
+    .map((group) => ({
+      group,
+      entries: entries
+        .filter((e) => e.group === group.key)
+        .sort((a, b) => (a.position ?? 100) - (b.position ?? 100)),
+    }))
+    .filter((g) => g.entries.length > 0)
+  return {
+    groups: grouped,
+    all: grouped.flatMap((g) => g.entries),
+  }
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+function getSnapshot() {
+  if (!snapshotCache) snapshotCache = buildSnapshot()
+  return snapshotCache
+}
+
+export function useSettingsNav() {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+/** Test-only: clear the registry. */
+export function __resetSettingsNavRegistry(): void {
+  entries.length = 0
+  groups.length = 0
+  notify()
+}

package/src/lib/slot-registry.ts

@@ -0,0 +1,116 @@
+import type { ComponentType } from 'react'
+import { useSyncExternalStore } from 'react'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Ambient context every slot receives, on top of slot-specific context.
+ * Populated by SlotProvider (see slot.tsx). Plugins reading these don't need
+ * to import auth/permission hooks — the slot machinery passes them through.
+ */
+export interface SlotAmbientContext {
+  permissions?: unknown
+  store?: unknown
+  user?: unknown
+}
+
+export interface SlotEntry<TContext = unknown> {
+  /** Unique within a slot. Required for removeSlot/updateSlot. */
+  id: string
+  component: ComponentType<TContext & SlotAmbientContext>
+  /** Lower numbers render first. Built-ins use 100/200/300 to leave gaps. */
+  position?: number
+  /** Visibility predicate. Receives the merged context. */
+  if?: (ctx: TContext & SlotAmbientContext) => boolean
+}
+
+// ============================================================================
+// Registry — module-singleton keyed by slot name
+// ============================================================================
+
+const registry = new Map<string, SlotEntry[]>()
+const listeners = new Set<() => void>()
+
+function notify() {
+  for (const listener of listeners) listener()
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+function getSnapshot(name: string): readonly SlotEntry[] {
+  return registry.get(name) ?? EMPTY
+}
+
+const EMPTY: readonly SlotEntry[] = Object.freeze([])
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export function registerSlot<TContext = unknown>(name: string, entry: SlotEntry<TContext>): void {
+  const list = registry.get(name) ?? []
+  if (list.some((e) => e.id === entry.id)) {
+    throw new Error(
+      `Slot "${name}" already has an entry with id "${entry.id}". Use updateSlot() instead.`,
+    )
+  }
+  registry.set(name, [...list, entry as SlotEntry])
+  notify()
+}
+
+export function removeSlot(name: string, id: string): void {
+  const list = registry.get(name)
+  if (!list) return
+  const next = list.filter((e) => e.id !== id)
+  if (next.length === list.length) return
+  registry.set(name, next)
+  notify()
+}
+
+export function updateSlot<TContext = unknown>(
+  name: string,
+  id: string,
+  patch: Partial<Omit<SlotEntry<TContext>, 'id'>>,
+): void {
+  const list = registry.get(name)
+  const entry = list?.find((e) => e.id === id)
+  if (!list || !entry) {
+    throw new Error(`Slot entry "${name}#${id}" not found.`)
+  }
+  registry.set(
+    name,
+    list.map((e) => (e.id === id ? ({ ...e, ...patch } as SlotEntry) : e)),
+  )
+  notify()
+}
+
+/**
+ * Subscribe to a slot's entries. Re-renders when entries are added/removed/updated
+ * so plugins registered after first render still appear.
+ *
+ * Returned entries are sorted by position (default 100) and stable within ties.
+ * Filtering by `if` happens at render time inside <Slot> — the hook returns the
+ * full registered list so the caller can decide how to combine context.
+ */
+export function useSlotEntries(name: string): readonly SlotEntry[] {
+  const entries = useSyncExternalStore(
+    subscribe,
+    () => getSnapshot(name),
+    () => getSnapshot(name),
+  )
+  // Sort by position (stable). Returned array is fresh; safe to reference in render.
+  return [...entries].sort((a, b) => (a.position ?? 100) - (b.position ?? 100))
+}
+
+/** Test-only: clear all registered slots. Not exported from the package index. */
+export function __resetSlotRegistry(): void {
+  registry.clear()
+  notify()
+}