@plutocms/pluto 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
 
+## [0.5.0](https://github.com/plutocms/pluto/compare/v0.4.0...v0.5.0) (2026-09-12)
+
+
+### Features
+
+* **permissions:** add capability registry and usePlutoPermissions composable ([#129](https://github.com/plutocms/pluto/issues/129)) ([c98419f](https://github.com/plutocms/pluto/commit/c98419fc967f8e20678389169e937db759c308bc))
+
+## [0.4.0](https://github.com/plutocms/pluto/compare/v0.3.2...v0.4.0) (2026-09-12)
+
+
+### Features
+
+* **registry:** add typed extension registry for admin UI ([#127](https://github.com/plutocms/pluto/issues/127)) ([f3c6b0a](https://github.com/plutocms/pluto/commit/f3c6b0a38870ab738b4267e8b6252bb0720dae13))
+
+
+### Bug Fixes
+
+* **deps:** move nuxt runtime modules to dependencies ([#125](https://github.com/plutocms/pluto/issues/125)) ([7d66096](https://github.com/plutocms/pluto/commit/7d660962dcd0b8ce7703da3487a861be2a5064a4)), closes [#79](https://github.com/plutocms/pluto/issues/79)
+
 ## [0.3.2](https://github.com/plutocms/pluto/compare/v0.3.1...v0.3.2) (2026-09-10)
 
 

package/FEATURES.md

@@ -5,3 +5,10 @@ with full detail, so this file stays short.
 
 See the workspace-level `CLAUDE.md` (one directory up) for the delegation, writing, and git
 policies shared by every project here.
+
+- Extension registry: a typed, ordered, reactive registry that lets a layer plug its admin-UI
+  pieces (navbar, sidebar nav, pages, dashboard widgets, settings panels and driver) into core
+  with one function call. @.claude/skills/extension-registry/SKILL.md
+- Permissions: a typed capability registry and a `usePlutoPermissions()` composable that let a
+  layer declare capabilities and check what the current user holds, backed by a registered
+  permissions driver. @.claude/skills/permissions/SKILL.md

package/README.md

@@ -69,9 +69,24 @@ The core layer provides the foundation for your CMS:
 - `<PlutoNavbarAdmin>` and `<PlutoNavbarAdminActions>`
   Provide structure for injecting actions from other layers
 
-Backend layers can provide the complete admin navbar with
-`useNavbarAdmin().registerNavbar(component)`. Feature layers can append controls
-with `useNavbarAdminActions().addAction(component)`.
+A layer plugs into the admin UI with one function, `definePlutoExtension`, called from a
+plugin. It registers any of: the admin navbar, navbar actions, sidebar nav entries, admin page
+metadata, dashboard widgets, and a settings panel or driver:
+
+```ts
+// app/plugins/pluto-registrations.ts
+export default defineNuxtPlugin(() => {
+  definePlutoExtension({
+    id: 'supabase-blog',
+    nav: [{ id: 'posts', label: 'Posts', icon: 'lucide:file-text', to: '/admin/posts' }],
+  })
+})
+```
+
+See `.claude/skills/extension-registry/SKILL.md` for the full type of each registrable thing
+and the ordering/dedupe rules. The old `useNavbarAdmin().registerNavbar(component)` and
+`useNavbarAdminActions().addAction(component)` composables still work, through a compatibility
+bridge, but `definePlutoExtension` is the current recommended way to plug in.
 
 ### Backend layers
 

package/app/components/Pluto/Admin/PlutoDashboardWidgets.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+const { items } = usePlutoDashboardWidgets()
+</script>
+
+<template>
+  <div v-if="items.length" class="grid grid-cols-1 gap-4 lg:grid-cols-3 lg:gap-x-4 lg:gap-y-6">
+    <div
+      v-for="widget in items"
+      :key="widget.id"
+      :class="{ 'lg:col-span-2': widget.colSpan === 2, 'lg:col-span-3': widget.colSpan === 3 }"
+    >
+      <component :is="widget.component" />
+    </div>
+  </div>
+
+  <UCard v-else>
+    <p class="text-muted text-sm">
+      No dashboard widgets are registered yet. A layer can add one with
+      <code>definePlutoExtension</code>.
+    </p>
+  </UCard>
+</template>

package/app/components/Pluto/Navbar/PlutoNavbarAdminActions.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
-const { actions } = useNavbarAdminActions()
+const { items } = usePlutoNavbarActions()
 </script>
 
 <template>
-  <component :is="action" v-for="(action, i) in actions" :key="i" />
+  <component :is="item.component" v-for="item in items" :key="item.id" />
 </template>

package/app/components/Pluto/PlutoRoot.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-const { navbar } = useNavbarAdmin()
+const { component: navbar } = usePlutoNavbarShell()
 </script>
 
 <template>

package/app/composables/internal/registry-factory.ts

@@ -0,0 +1,63 @@
+// Nuxt auto-imports `app/composables/*.ts` at depth 1 only, so this file
+// sits under `internal/` on purpose: it stays out of auto-import, and it can
+// be unit-tested directly with an explicit import, outside a Nuxt build
+// context. Import from 'vue' explicitly here, instead of relying on
+// auto-import, so this file works the same way under plain Vitest.
+import type { ComputedRef } from 'vue'
+import { computed, markRaw, shallowRef } from 'vue'
+
+export interface OwnedEntry {
+  id: string
+  order?: number
+  enabled?: () => boolean
+}
+
+/**
+ * An owner-keyed registry. Each owner (a layer id) contributes a list of
+ * entries. Calling `set` again for the same owner replaces its whole
+ * contribution — this makes registration idempotent, so re-running a
+ * plugin (for example on HMR) never duplicates entries and needs no
+ * dedupe warning.
+ *
+ * `list` merges every owner's entries, drops disabled ones, and sorts by
+ * `order` (default 100), breaking ties by first-registration sequence.
+ */
+export function createOwnedRegistry<T extends OwnedEntry>() {
+  const owners = shallowRef<Map<string, T[]>>(new Map())
+  let sequence = 0
+  const seq = new Map<string, number>()
+
+  function set(owner: string, entries: T[]) {
+    const next = new Map(owners.value)
+    next.set(
+      owner,
+      entries.map((entry) => {
+        const id = `${owner}:${entry.id}`
+        if (!seq.has(id)) {
+          seq.set(id, sequence++)
+        }
+        return markRaw({ ...entry, id }) as T
+      })
+    )
+    owners.value = next
+  }
+
+  function remove(owner: string) {
+    const next = new Map(owners.value)
+    next.delete(owner)
+    owners.value = next
+  }
+
+  const list: ComputedRef<T[]> = computed(() =>
+    [...owners.value.values()]
+      .flat()
+      .filter((entry) => entry.enabled?.() ?? true)
+      .sort(
+        (a, b) =>
+          (a.order ?? 100) - (b.order ?? 100) ||
+          (seq.get(a.id) ?? 0) - (seq.get(b.id) ?? 0)
+      )
+  )
+
+  return { set, remove, list }
+}

package/app/composables/pluto-admin-nav.ts

@@ -0,0 +1,44 @@
+// The old `NavigationMenuItem`/`NavigationMenuChildItem` shape (from
+// `@plutocms/utils`) always carries a plain `href`, never Nuxt's typed `to`.
+// This narrows just the field the bridge below reads.
+interface LegacyHrefLink {
+  href?: string
+}
+
+/**
+ * The admin sidebar nav. Merges the new registry with the old
+ * `useSidebarAdminActions` composable (`@plutocms/utils`), so an unmigrated
+ * layer's sidebar entries keep showing up. A bridged entry is skipped when a
+ * registered entry already uses the same label, so a layer that migrates
+ * does not get a duplicate item.
+ */
+export function usePlutoAdminNav() {
+  const registry = usePlutoRegistry()
+  const legacy = useSidebarAdminActions()
+
+  const items = computed<PlutoNavItem[]>(() => {
+    const registered = registry.nav.list.value
+    const seen = new Set(registered.map((item) => item.label))
+
+    const bridged = legacy.actions.value
+      .filter((action) => !seen.has(String(action.label)))
+      .map((action, index) => ({
+        id: `legacy:sidebar-${index}`,
+        order: 500,
+        label: String(action.label ?? ''),
+        icon: action.icon,
+        to: (action as LegacyHrefLink).href,
+        defaultOpen: action.defaultOpen,
+        children: (action.children ?? []).map((child) => ({
+          label: String(child.label ?? ''),
+          to: (child as LegacyHrefLink).href ?? '',
+        })),
+      }))
+
+    return [...registered, ...bridged].sort(
+      (a, b) => (a.order ?? 100) - (b.order ?? 100)
+    )
+  })
+
+  return { items }
+}

package/app/composables/pluto-admin-pages.ts

@@ -0,0 +1,14 @@
+/**
+ * Metadata for admin pages, registered on top of routes Nuxt already
+ * creates from files. No layer registers page metadata today, so this has
+ * no legacy bridge.
+ */
+export function usePlutoAdminPages() {
+  const registry = usePlutoRegistry()
+  const route = useRoute()
+
+  const items = computed(() => registry.pages.list.value)
+  const current = computed(() => items.value.find((page) => page.path === route.path))
+
+  return { items, current }
+}

package/app/composables/pluto-dashboard.ts

@@ -0,0 +1,5 @@
+/** Widgets shown on the admin dashboard (`/admin/home`). */
+export function usePlutoDashboardWidgets() {
+  const registry = usePlutoRegistry()
+  return { items: registry.dashboardWidgets.list }
+}

package/app/composables/pluto-extension.ts

@@ -0,0 +1,29 @@
+/**
+ * The one function a layer author calls to plug into the admin UI. Every
+ * bucket gets set for this extension's id on every call, so a layer's whole
+ * admin-UI contribution lives in one place.
+ *
+ * Call this from a plugin (`app/plugins/*.ts`). Calling it again with the
+ * same `id` replaces that layer's whole contribution — it does not add to
+ * it — so re-running the plugin (for example on HMR) never duplicates
+ * entries.
+ */
+export function definePlutoExtension(definition: PlutoExtension): void {
+  const registry = usePlutoRegistry()
+
+  registry.navbarShell.set(definition.id, definition.navbar ? [definition.navbar] : [])
+  registry.navbarActions.set(definition.id, definition.navbarActions ?? [])
+  registry.nav.set(definition.id, definition.nav ?? [])
+  registry.pages.set(definition.id, definition.pages ?? [])
+  registry.settingsPanels.set(definition.id, definition.settingsPanels ?? [])
+  registry.settingsDrivers.set(
+    definition.id,
+    definition.settingsDriver ? [definition.settingsDriver] : []
+  )
+  registry.dashboardWidgets.set(definition.id, definition.dashboardWidgets ?? [])
+  registry.capabilities.set(definition.id, definition.capabilities ?? [])
+  registry.permissionsDrivers.set(
+    definition.id,
+    definition.permissionsDriver ? [definition.permissionsDriver] : []
+  )
+}

package/app/composables/pluto-navbar.ts

@@ -0,0 +1,40 @@
+/**
+ * The admin navbar shell (the whole top bar, provided by a backend layer).
+ * Reads the new registry and falls back to the old `useNavbarAdmin`
+ * composable (`@plutocms/utils`) when no layer has migrated yet. The legacy
+ * ref is read inside this `computed`, not once at setup, so a navbar
+ * registered after this composable first runs is never lost.
+ */
+export function usePlutoNavbarShell() {
+  const registry = usePlutoRegistry()
+  const legacy = useNavbarAdmin()
+
+  const component = computed<Component | null>(() => {
+    const registered = registry.navbarShell.list.value
+    const winner = registered.at(-1) // highest-order wins; ties go to most recent
+    return winner?.component ?? legacy.navbar.value ?? null
+  })
+
+  return { component }
+}
+
+/**
+ * The small action buttons rendered inside the navbar. Merges the new
+ * registry with the old `useNavbarAdminActions` composable
+ * (`@plutocms/utils`), so an unmigrated layer's actions keep showing up.
+ */
+export function usePlutoNavbarActions() {
+  const registry = usePlutoRegistry()
+  const legacy = useNavbarAdminActions()
+
+  const items = computed<PlutoNavbarAction[]>(() => [
+    ...registry.navbarActions.list.value,
+    ...legacy.actions.value.map((component, index) => ({
+      id: `legacy:navbar-action-${index}`,
+      order: 500,
+      component,
+    })),
+  ])
+
+  return { items }
+}

package/app/composables/pluto-permissions.ts

@@ -0,0 +1,74 @@
+/** Capabilities declared by every layer, in registry order. */
+export function usePlutoCapabilities() {
+  const registry = usePlutoRegistry()
+  return { items: registry.capabilities.list }
+}
+
+/**
+ * The current user's capabilities, backed by whichever permissions driver
+ * is registered. `useState` is correct for the loaded list itself (plain
+ * strings, and /admin/** is client-only per nuxt.config.ts) — this
+ * mirrors usePlutoSettings()'s values/dirty state exactly. The driver
+ * registration itself goes through the registry, same as
+ * PlutoSettingsDriver.
+ */
+export function usePlutoPermissions() {
+  const registry = usePlutoRegistry()
+  const driver = computed(() => registry.permissionsDrivers.list.value.at(-1) ?? null)
+
+  const granted = useState<string[]>('pluto-permissions-granted', () => [])
+  const loaded = useState<boolean>('pluto-permissions-loaded', () => false)
+  const status = ref<'idle' | 'loading'>('idle')
+
+  async function load() {
+    if (!driver.value) {
+      return
+    }
+
+    status.value = 'loading'
+    try {
+      granted.value = await driver.value.load()
+      loaded.value = true
+    } finally {
+      status.value = 'idle'
+    }
+  }
+
+  function clear() {
+    granted.value = []
+    loaded.value = false
+  }
+
+  /**
+   * True when the user holds this capability.
+   *
+   * Fails OPEN when no permissions driver is registered — a site with no
+   * permissions backend also has no server-side guard, so hiding UI in
+   * that case would only be theatre, and would break a core-only
+   * install with nothing registered yet. Read `hasDriver` to tell the two
+   * cases apart if a caller needs to.
+   *
+   * This is never a security boundary by itself. The server-side guard
+   * (a backend layer's own requireCapability-equivalent, backed by RLS)
+   * is what actually enforces anything. This only decides what the UI
+   * shows.
+   */
+  function can(capability: string): boolean {
+    if (!driver.value) {
+      return true
+    }
+
+    return granted.value.includes('*') || granted.value.includes(capability)
+  }
+
+  return {
+    granted,
+    loaded,
+    status,
+    hasDriver: computed(() => Boolean(driver.value)),
+    isAdmin: computed(() => granted.value.includes('*')),
+    load,
+    clear,
+    can,
+  }
+}

package/app/composables/pluto-registry.ts

@@ -0,0 +1,34 @@
+import { createOwnedRegistry } from './internal/registry-factory'
+
+/**
+ * The one registry container for this Nuxt app instance. Created lazily on
+ * `nuxtApp`, not at module scope, so it is per-request on the server and
+ * per-app on the client — never a process-wide singleton, and never
+ * serialized into the SSR payload.
+ *
+ * No plugin-ordering contract is needed: a layer's plugin can call this
+ * before or after any other layer's plugin.
+ */
+export function usePlutoRegistry(): PlutoRegistry {
+  const nuxtApp = useNuxtApp()
+
+  if (!nuxtApp._plutoRegistry) {
+    nuxtApp._plutoRegistry = {
+      navbarShell: createOwnedRegistry<PlutoNavbarShell>(),
+      navbarActions: createOwnedRegistry<PlutoNavbarAction>(),
+      nav: createOwnedRegistry<PlutoNavItem>(),
+      pages: createOwnedRegistry<PlutoAdminPage>(),
+      settingsPanels: createOwnedRegistry<PlutoSettingsPanel>(),
+      settingsDrivers: createOwnedRegistry<PlutoSettingsDriver>(),
+      dashboardWidgets: createOwnedRegistry<PlutoDashboardWidget>(),
+      capabilities: createOwnedRegistry<PlutoCapability>(),
+      permissionsDrivers: createOwnedRegistry<PlutoPermissionsDriver>(),
+    }
+  }
+
+  // Cast rather than rely on control-flow narrowing of a global-augmented
+  // property: that narrowing is fragile across vue-tsc's separate project
+  // references (app/server/shared), and has been observed to resolve to
+  // `unknown` instead of `PlutoRegistry` in some of them.
+  return nuxtApp._plutoRegistry as PlutoRegistry
+}

package/app/composables/pluto-settings.ts

@@ -0,0 +1,65 @@
+/** Settings panels registered by every layer, in registry order. */
+export function usePlutoSettingsPanels() {
+  const registry = usePlutoRegistry()
+  return { items: registry.settingsPanels.list }
+}
+
+/**
+ * The settings value store, backed by whichever settings driver is
+ * registered. `useState` is correct here: these are plain strings, not
+ * components, and `/admin/**` is client-only per `nuxt.config.ts`, so there
+ * is no SSR-serialization concern.
+ */
+export function usePlutoSettings() {
+  const registry = usePlutoRegistry()
+  const driver = computed(() => registry.settingsDrivers.list.value.at(-1) ?? null)
+
+  const values = useState<Record<string, string>>('pluto-settings-values', () => ({}))
+  const dirty = useState<Record<string, string>>('pluto-settings-dirty', () => ({}))
+  const status = ref<'idle' | 'loading' | 'saving'>('idle')
+
+  async function load() {
+    if (!driver.value) {
+      return
+    }
+    status.value = 'loading'
+    try {
+      values.value = await driver.value.load()
+    } finally {
+      status.value = 'idle'
+    }
+  }
+
+  async function save() {
+    if (!driver.value) {
+      return
+    }
+    status.value = 'saving'
+    try {
+      await driver.value.save(dirty.value)
+      values.value = { ...values.value, ...dirty.value }
+      dirty.value = {}
+    } finally {
+      status.value = 'idle'
+    }
+  }
+
+  function field(key: string, fallback = '') {
+    return computed<string>({
+      get: () => dirty.value[key] ?? values.value[key] ?? fallback,
+      set: (value) => {
+        dirty.value[key] = value
+      },
+    })
+  }
+
+  return {
+    values,
+    dirty,
+    status,
+    hasDriver: computed(() => Boolean(driver.value)),
+    load,
+    save,
+    field,
+  }
+}

package/app/layouts/admin.vue

@@ -6,7 +6,28 @@ import type { NavigationMenuItem } from '@nuxt/ui'
 // so drop `to` here to avoid a cross-app type mismatch on that field.
 type SidebarMenuItem = Omit<NavigationMenuItem, 'to'>
 
-const { actions: sidebarActions } = useSidebarAdminActions()
+function toMenuItem(item: PlutoNavItem): SidebarMenuItem {
+  return {
+    label: item.label,
+    icon: item.icon,
+    href: item.to,
+    // Top-level items SPA-navigate instead of doing a full page load. This
+    // matches what supabase-blog and supabase-shop's own (pre-registry)
+    // sidebar entries already did — the registry now does it for every
+    // item instead of only theirs. Children stay href-only, same as those
+    // two layers' own child entries did.
+    onSelect: item.to ? () => navigateTo(item.to) : undefined,
+    defaultOpen: item.defaultOpen,
+    children: item.children?.map((child) => ({
+      label: child.label,
+      href: child.to,
+    })),
+  }
+}
+
+const { items: navItems } = usePlutoAdminNav()
+const menu = computed<SidebarMenuItem[]>(() => navItems.value.map(toMenuItem))
+
 const route = useRoute()
 const isSidebarOpen = useState<boolean>('pluto-admin-sidebar-open', () => false)
 
@@ -14,20 +35,6 @@ function closeSidebar() {
   isSidebarOpen.value = false
 }
 
-const menu = shallowRef<SidebarMenuItem[]>([
-  {
-    label: 'Home',
-    href: '/admin/home',
-    icon: 'lucide:house',
-  },
-  ...(sidebarActions.value as unknown as SidebarMenuItem[]),
-  {
-    label: 'Settings',
-    href: '/admin/settings',
-    icon: 'lucide:settings',
-  },
-])
-
 watch(
   () => route.fullPath,
   closeSidebar

package/app/pages/admin/home.vue

@@ -9,13 +9,7 @@ useHead({
     <AdminView>
       <h1 class="text-3xl font-bold lg:text-4xl">Admin Dashboard</h1>
 
-      <div class="grid grid-cols-1 gap-4 lg:grid-cols-3 lg:gap-x-4 lg:gap-y-6">
-        <div
-          v-for="i in 6"
-          :key="i"
-          class="h-50 rounded-3xl border border-gray-500"
-        />
-      </div>
+      <PlutoDashboardWidgets />
     </AdminView>
   </main>
 </template>

package/app/pages/admin/settings.vue

@@ -0,0 +1,46 @@
+<script setup lang="ts">
+useHead({
+  title: 'Settings',
+})
+
+const { items } = usePlutoSettingsPanels()
+const { hasDriver, status, load, save } = usePlutoSettings()
+
+onMounted(() => {
+  if (hasDriver.value) {
+    load()
+  }
+})
+</script>
+
+<template>
+  <main>
+    <AdminView>
+      <h1 class="text-3xl font-bold lg:text-4xl">Settings</h1>
+
+      <UAlert
+        v-if="!hasDriver"
+        color="warning"
+        title="No settings storage"
+        description="No installed layer provides settings storage yet."
+      />
+
+      <template v-else>
+        <UCard v-for="panel in items" :key="panel.id">
+          <template #header>
+            <h2 class="font-semibold">{{ panel.title }}</h2>
+            <p v-if="panel.description" class="text-muted text-sm">{{ panel.description }}</p>
+          </template>
+
+          <component :is="panel.component" />
+        </UCard>
+
+        <div class="flex">
+          <UButton :loading="status === 'saving'" icon="lucide:save" @click="save">
+            Save
+          </UButton>
+        </div>
+      </template>
+    </AdminView>
+  </main>
+</template>

package/app/plugins/pluto-core-registrations.ts

@@ -0,0 +1,16 @@
+// Registers core's own Home and Settings anchors. `order: 0` and
+// `order: 1000` are reserved for these two entries, so every other layer's
+// nav item sorts between them by default (default order is 100).
+export default defineNuxtPlugin(() => {
+  definePlutoExtension({
+    id: 'pluto',
+    nav: [
+      { id: 'home', order: 0, label: 'Home', icon: 'lucide:house', to: '/admin/home' },
+      { id: 'settings', order: 1000, label: 'Settings', icon: 'lucide:settings', to: '/admin/settings' },
+    ],
+    pages: [
+      { id: 'home', path: '/admin/home', title: 'Dashboard', icon: 'lucide:house' },
+      { id: 'settings', path: '/admin/settings', title: 'Settings', icon: 'lucide:settings' },
+    ],
+  })
+})

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/pluto",
   "type": "module",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "The layerable CMS",
   "author": "Victor Ribeiro",
   "license": "MIT",
@@ -44,13 +44,15 @@
   "dependencies": {
     "@iconify-json/lucide": "^1.2.116",
     "@iconify-json/simple-icons": "^1.2.89",
+    "@nuxt/eslint": "^1.16.0",
+    "@nuxt/ui": "^4.9.0",
     "@plutocms/utils": "^0.2.1",
-    "@vueuse/nuxt": "^14.3.0"
+    "@vueuse/nuxt": "^14.3.0",
+    "reka-ui": "^2.10.1",
+    "tailwind-merge": "^3.6.0"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.1.0",
-    "@nuxt/eslint": "^1.16.0",
-    "@nuxt/ui": "^4.9.0",
     "@tailwindcss/vite": "^4.2.1",
     "@types/bun": "^1.3.14",
     "eslint": "^10.6.0",
@@ -58,8 +60,6 @@
     "nuxt": "^4.3.1",
     "prettier": "^3.9.4",
     "prettier-plugin-tailwindcss": "^0.8.0",
-    "reka-ui": "^2.10.1",
-    "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.2",
     "typescript": "6.0.3",
     "vitest": "^5.0.0",

package/shared/types/registry.d.ts

@@ -0,0 +1,14 @@
+import type { PlutoRegistry } from './registry'
+
+// Lives in `shared/` (as a `.d.ts` file) so every generated Nuxt TS project
+// (app, server, shared) picks it up automatically, the same way
+// `runtime-config.d.ts` augments `@nuxt/schema`'s `RuntimeConfig` in
+// `@plutocms/supabase`. `_plutoRegistry` is created lazily per `NuxtApp`
+// instance by `usePlutoRegistry` — see `app/composables/pluto-registry.ts`.
+declare module '#app' {
+  interface NuxtApp {
+    _plutoRegistry?: PlutoRegistry
+  }
+}
+
+export {}

package/shared/types/registry.ts

@@ -0,0 +1,124 @@
+import type { Component, ComputedRef } from 'vue'
+
+export interface PlutoEntry {
+  /** Unique inside this extension. Stored as `<extensionId>:<id>`. */
+  id: string
+  /** Lower comes first. Default 100. Core uses 0 for Home and 1000 for Settings. */
+  order?: number
+  /** Reactive visibility test. Called inside a computed. */
+  enabled?: () => boolean
+}
+
+export interface PlutoNavChild {
+  label: string
+  to: string
+}
+
+export interface PlutoNavItem extends PlutoEntry {
+  label: string
+  icon?: string
+  /** Admin route path, for example '/admin/posts'. Plain string on purpose. */
+  to?: string
+  children?: PlutoNavChild[]
+  defaultOpen?: boolean
+}
+
+export interface PlutoNavbarShell extends PlutoEntry {
+  component: Component
+}
+
+export interface PlutoNavbarAction extends PlutoEntry {
+  component: Component
+}
+
+export interface PlutoAdminPage extends PlutoEntry {
+  /** The route Nuxt already created from a file. This registry only adds metadata. */
+  path: string
+  title: string
+  icon?: string
+  /** Full id of a parent page (e.g. 'supabase-blog:posts'), for a breadcrumb trail. */
+  parent?: string
+}
+
+export interface PlutoDashboardWidget extends PlutoEntry {
+  component: Component
+  title?: string
+  /** Grid columns on large screens. 1 to 3. Default 1. */
+  colSpan?: 1 | 2 | 3
+}
+
+export interface PlutoSettingsPanel extends PlutoEntry {
+  title: string
+  description?: string
+  icon?: string
+  component: Component
+}
+
+export interface PlutoSettingsDriver extends PlutoEntry {
+  load: () => Promise<Record<string, string>>
+  save: (patch: Record<string, string>) => Promise<void>
+}
+
+/**
+ * A capability a layer defines. `key` is the real capability string, for
+ * example 'posts:publish'. It is kept separate from `id` on purpose: the
+ * registry rewrites `id` to '<extensionId>:<id>' (see registry-factory.ts),
+ * which would corrupt a capability string if `id` were reused as the
+ * capability itself. `id` identifies this registry entry; `key` identifies
+ * the permission.
+ */
+export interface PlutoCapability extends PlutoEntry {
+  /** Format: '<namespace>:<action>', lowercase, for example 'posts:publish'. */
+  key: string
+  label: string
+  description?: string
+}
+
+/**
+ * Loads the current user's capability list. One backend layer registers
+ * this, the same way one layer registers a PlutoSettingsDriver. `load`
+ * returns a flat list of capability key strings the user holds. The
+ * single entry '*' means "every capability" (used by the built-in admin
+ * role).
+ */
+export interface PlutoPermissionsDriver extends PlutoEntry {
+  load: () => Promise<string[]>
+}
+
+export interface PlutoExtension {
+  /** Layer name. Use the package's $meta.name, e.g. 'supabase-blog'. */
+  id: string
+  navbar?: PlutoNavbarShell
+  navbarActions?: PlutoNavbarAction[]
+  nav?: PlutoNavItem[]
+  pages?: PlutoAdminPage[]
+  dashboardWidgets?: PlutoDashboardWidget[]
+  settingsPanels?: PlutoSettingsPanel[]
+  settingsDriver?: PlutoSettingsDriver
+  capabilities?: PlutoCapability[]
+  permissionsDriver?: PlutoPermissionsDriver
+}
+
+/**
+ * The shape `createOwnedRegistry` returns, one per registrable thing. Declared
+ * again here, rather than imported from `app/composables/internal`, because
+ * the shared TS project does not include `app/`. Structural typing keeps this
+ * in sync with the real return type.
+ */
+export interface PlutoRegistryBucket<T extends PlutoEntry> {
+  set: (owner: string, entries: T[]) => void
+  remove: (owner: string) => void
+  list: ComputedRef<T[]>
+}
+
+export interface PlutoRegistry {
+  navbarShell: PlutoRegistryBucket<PlutoNavbarShell>
+  navbarActions: PlutoRegistryBucket<PlutoNavbarAction>
+  nav: PlutoRegistryBucket<PlutoNavItem>
+  pages: PlutoRegistryBucket<PlutoAdminPage>
+  settingsPanels: PlutoRegistryBucket<PlutoSettingsPanel>
+  settingsDrivers: PlutoRegistryBucket<PlutoSettingsDriver>
+  dashboardWidgets: PlutoRegistryBucket<PlutoDashboardWidget>
+  capabilities: PlutoRegistryBucket<PlutoCapability>
+  permissionsDrivers: PlutoRegistryBucket<PlutoPermissionsDriver>
+}