@plutocms/pluto 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
 
+## [0.7.0](https://github.com/plutocms/pluto/compare/v0.6.0...v0.7.0) (2026-09-12)
+
+
+### Features
+
+* **content:** add server-side content registry and generic CRUD routes (wave 2) ([#133](https://github.com/plutocms/pluto/issues/133)) ([7846340](https://github.com/plutocms/pluto/commit/784634081f5a267fbe33dde8264e6b848bf7bdda))
+
+## [0.6.0](https://github.com/plutocms/pluto/compare/v0.5.0...v0.6.0) (2026-09-12)
+
+
+### Features
+
+* **content:** add content-model contracts (wave 1) ([#131](https://github.com/plutocms/pluto/issues/131)) ([95e157b](https://github.com/plutocms/pluto/commit/95e157b41a60b17ae8311878eb2ef79356feef43))
+
 ## [0.5.0](https://github.com/plutocms/pluto/compare/v0.4.0...v0.5.0) (2026-09-12)
 
 

package/FEATURES.md

@@ -12,3 +12,8 @@ policies shared by every project here.
 - 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
+- Content model: a typed content-type contract (`defineContentType`, field types, payload
+  validation, field-to-column mapping) and a media-adapter contract, with registry wiring and
+  consumer composables, plus a server-side content registry and generic list/get/create/update/
+  delete routes backed by a `PlutoContentAdapter` a backend layer implements. No real adapter or
+  generated UI yet. @.claude/skills/content-model/SKILL.md

package/app/composables/pluto-content-fields.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolves the component that renders `field` in the generic content form
+ * (a later wave). Matches an exact `widget` name first — a field can force
+ * a specific widget through `PlutoFieldBase.widget` — then falls back to
+ * the last-registered entry for the field's `type`. Returns `undefined`
+ * when nothing matches: this wave adds no fallback placeholder component,
+ * that is later, UI-wave work.
+ */
+export function usePlutoContentFieldWidget(field: PlutoField) {
+  const registry = usePlutoRegistry()
+
+  return computed<Component | undefined>(() => {
+    const entries = registry.contentFieldWidgets.list.value
+
+    if (field.widget) {
+      const exact = entries.find((entry) => entry.widget === field.widget)
+      if (exact) {
+        return exact.component
+      }
+    }
+
+    return entries.filter((entry) => entry.fieldType === field.type).at(-1)?.component
+  })
+}

package/app/composables/pluto-content-types.ts

@@ -0,0 +1,11 @@
+/** Content types declared by every layer, in registry order. */
+export function usePlutoContentTypes() {
+  const registry = usePlutoRegistry()
+
+  /** Looks up a content type by its own `name`, not the registry entry `id`. */
+  function byName(name: string): PlutoContentType | undefined {
+    return registry.contentTypes.list.value.find((entry) => entry.type.name === name)?.type
+  }
+
+  return { items: registry.contentTypes.list, byName }
+}

package/app/composables/pluto-extension.ts

@@ -26,4 +26,7 @@ export function definePlutoExtension(definition: PlutoExtension): void {
     definition.id,
     definition.permissionsDriver ? [definition.permissionsDriver] : []
   )
+  registry.contentTypes.set(definition.id, definition.contentTypes ?? [])
+  registry.contentFieldWidgets.set(definition.id, definition.contentFieldWidgets ?? [])
+  registry.mediaAdapters.set(definition.id, definition.mediaAdapters ?? [])
 }

package/app/composables/pluto-media-adapter.ts

@@ -0,0 +1,15 @@
+/**
+ * The registered media adapter. Only one is meaningful per app: when more
+ * than one layer registers one, the last-registered entry wins, the same
+ * "last wins" rule `usePlutoSettings`/`usePlutoPermissions` use to resolve
+ * their driver.
+ */
+export function usePlutoMediaAdapter() {
+  const registry = usePlutoRegistry()
+
+  const adapter = computed<PlutoMediaAdapter | undefined>(
+    () => registry.mediaAdapters.list.value.at(-1)?.adapter
+  )
+
+  return { adapter }
+}

package/app/composables/pluto-registry.ts

@@ -23,6 +23,9 @@ export function usePlutoRegistry(): PlutoRegistry {
       dashboardWidgets: createOwnedRegistry<PlutoDashboardWidget>(),
       capabilities: createOwnedRegistry<PlutoCapability>(),
       permissionsDrivers: createOwnedRegistry<PlutoPermissionsDriver>(),
+      contentTypes: createOwnedRegistry<PlutoContentTypeEntry>(),
+      contentFieldWidgets: createOwnedRegistry<PlutoContentFieldWidget>(),
+      mediaAdapters: createOwnedRegistry<PlutoMediaAdapterEntry>(),
     }
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/pluto",
   "type": "module",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "The layerable CMS",
   "author": "Victor Ribeiro",
   "license": "MIT",

package/server/api/_pluto/content/[type]/[id].delete.ts

@@ -0,0 +1,15 @@
+/**
+ * Deletes one item of one content type. Generic, core-internal route — see
+ * the content-model skill for the `/_pluto/` prefix and the
+ * delete-capability enforcement this route follows.
+ */
+export default defineEventHandler(async (event) => {
+  const typeName = getRouterParam(event, 'type')
+  const type = requireContentType(typeName ?? '')
+
+  const id = getRouterParam(event, 'id') ?? ''
+
+  await deleteContentItem({ event, type }, id)
+
+  return { success: true }
+})

package/server/api/_pluto/content/[type]/[id].get.ts

@@ -0,0 +1,13 @@
+/**
+ * Gets one item of one content type, by id or slug. Generic, core-internal
+ * route — see the content-model skill for the `/_pluto/` prefix and the
+ * capability rule this route follows (no `read` capability check, ever).
+ */
+export default defineEventHandler(async (event) => {
+  const typeName = getRouterParam(event, 'type')
+  const type = requireContentType(typeName ?? '')
+
+  const idOrSlug = getRouterParam(event, 'id') ?? ''
+
+  return getContentItem({ event, type }, idOrSlug)
+})

package/server/api/_pluto/content/[type]/[id].patch.ts

@@ -0,0 +1,14 @@
+/**
+ * Updates one item of one content type. Generic, core-internal route — see
+ * the content-model skill for the `/_pluto/` prefix, partial-payload
+ * validation, and the write-capability enforcement this route follows.
+ */
+export default defineEventHandler(async (event) => {
+  const typeName = getRouterParam(event, 'type')
+  const type = requireContentType(typeName ?? '')
+
+  const id = getRouterParam(event, 'id') ?? ''
+  const body = await readBody(event)
+
+  return updateContentItem({ event, type }, id, body)
+})

package/server/api/_pluto/content/[type]/index.get.ts

@@ -0,0 +1,16 @@
+/**
+ * Lists items of one content type. Generic, core-internal route — see the
+ * content-model skill for the `/_pluto/` prefix and the capability rule
+ * this route follows (no `read` capability check, ever).
+ */
+export default defineEventHandler(async (event) => {
+  const typeName = getRouterParam(event, 'type')
+  const type = requireContentType(typeName ?? '')
+
+  const query = getQuery(event)
+  const limit = query.limit === undefined ? undefined : Number.parseInt(query.limit as string, 10)
+  const offset = query.offset === undefined ? undefined : Number.parseInt(query.offset as string, 10)
+  const search = query.search === undefined ? undefined : String(query.search)
+
+  return listContentItems({ event, type }, { limit, offset, search })
+})

package/server/api/_pluto/content/[type]/index.post.ts

@@ -0,0 +1,13 @@
+/**
+ * Creates one item of one content type. Generic, core-internal route — see
+ * the content-model skill for the `/_pluto/` prefix, payload validation,
+ * and the write-capability enforcement this route follows.
+ */
+export default defineEventHandler(async (event) => {
+  const typeName = getRouterParam(event, 'type')
+  const type = requireContentType(typeName ?? '')
+
+  const body = await readBody(event)
+
+  return createContentItem({ event, type }, body)
+})

package/server/utils/pluto-content-handlers.ts

@@ -0,0 +1,168 @@
+import type { H3Event } from 'h3'
+import { createError } from 'h3'
+import { validateContentPayload } from '../../shared/utils/content-validate'
+import { getContentAdapter, getContentType } from './pluto-content'
+
+/**
+ * The real logic behind the generic content routes, kept in plain exported
+ * functions — not inline in a `server/api/**` route file — so it can be
+ * unit-tested by calling it directly, the same way this workspace already
+ * tests everything else: no live Nitro server, no `@nuxt/test-utils`.
+ */
+
+export function requireContentType(name: string): PlutoContentType {
+  const type = getContentType(name)
+
+  if (!type) {
+    throw createError({ statusCode: 404, statusMessage: `Content type "${name}" not found.` })
+  }
+
+  return type
+}
+
+export function requireContentAdapter(): PlutoContentAdapter {
+  const adapter = getContentAdapter()
+
+  if (!adapter) {
+    throw createError({ statusCode: 500, statusMessage: 'No content adapter is registered.' })
+  }
+
+  return adapter
+}
+
+/**
+ * Checks `capability` against `event`, but only when there is something to
+ * check against. Exported because both write handlers below share it, and
+ * a test exercises it indirectly through them.
+ *
+ * Fails open on purpose, in two cases:
+ * - `capability` is undefined (the content type declares no capability for
+ *   this operation): nothing to enforce, anyone who can reach the route
+ *   may proceed.
+ * - The registered adapter has no `authorize` method: the same fail-open
+ *   rule `usePlutoPermissions().can()` already documents for "no
+ *   permissions backend registered at all" — with no boundary to enforce,
+ *   the adapter's own backing store (RLS, or equivalent) is still the real
+ *   gate.
+ */
+export async function authorizeContentOperation(event: H3Event, capability: string | undefined): Promise<void> {
+  if (!capability) {
+    return
+  }
+
+  const adapter = requireContentAdapter()
+
+  if (!adapter.authorize) {
+    return
+  }
+
+  await adapter.authorize(event, capability)
+}
+
+/**
+ * Lists items for `ctx.type`. Never checks `type.capabilities.read` and
+ * never calls `adapter.authorize` — see the content-model skill for why:
+ * in short, "read" is not all-or-nothing for a type like `posts` (an
+ * anonymous visitor can read published posts; only drafts need a
+ * capability), and that distinction already lives in the adapter's backing
+ * store (RLS, for the one adapter that exists so far). This route always
+ * asks the adapter for everything, unfiltered by capability, because it is
+ * admin-surface-only in intent — a public-facing read path is a layer's
+ * own hand-written endpoint, not this generic one.
+ */
+export async function listContentItems(
+  ctx: PlutoContentContext,
+  query: {
+    limit?: number
+    offset?: number
+    search?: string
+  }
+): Promise<PlutoContentListResult> {
+  return requireContentAdapter().list(ctx, {
+    limit: query.limit,
+    offset: query.offset,
+    search: query.search,
+    sort: ctx.type.defaultSort,
+    includeUnpublished: true,
+  })
+}
+
+/** Gets one item by id or slug. No capability check — see `listContentItems`. */
+export async function getContentItem(ctx: PlutoContentContext, idOrSlug: string | number): Promise<PlutoContentItem> {
+  const item = await requireContentAdapter().get(ctx, idOrSlug)
+
+  if (!item) {
+    throw createError({ statusCode: 404, statusMessage: 'Not found.' })
+  }
+
+  return item
+}
+
+function requirePlainObjectBody(body: unknown): Record<string, unknown> {
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+    throw createError({ statusCode: 400, statusMessage: 'Request body must be a JSON object.' })
+  }
+
+  return body as Record<string, unknown>
+}
+
+/**
+ * Creates one item. Validates the full payload (not partial), authorizes
+ * against `type.capabilities.write`, then calls the adapter, then runs
+ * `type.hooks.afterCreate` when one is registered. A hook error propagates
+ * — it is not swallowed.
+ */
+export async function createContentItem(ctx: PlutoContentContext, body: unknown): Promise<PlutoContentItem> {
+  const payload = requirePlainObjectBody(body)
+
+  const errors = validateContentPayload(ctx.type, payload)
+  if (errors.length > 0) {
+    throw createError({ statusCode: 400, statusMessage: 'Validation failed.', data: { errors } })
+  }
+
+  await authorizeContentOperation(ctx.event, ctx.type.capabilities?.write)
+
+  const item = await requireContentAdapter().create(ctx, payload)
+
+  if (ctx.type.hooks?.afterCreate) {
+    await ctx.type.hooks.afterCreate(ctx, item, payload)
+  }
+
+  return item
+}
+
+/**
+ * Updates one item. Validates the payload as a partial update, authorizes
+ * against `type.capabilities.write`, then calls the adapter, then runs
+ * `type.hooks.afterUpdate` when one is registered. A hook error propagates
+ * — it is not swallowed.
+ */
+export async function updateContentItem(
+  ctx: PlutoContentContext,
+  id: string | number,
+  body: unknown
+): Promise<PlutoContentItem> {
+  const payload = requirePlainObjectBody(body)
+
+  const errors = validateContentPayload(ctx.type, payload, { partial: true })
+  if (errors.length > 0) {
+    throw createError({ statusCode: 400, statusMessage: 'Validation failed.', data: { errors } })
+  }
+
+  await authorizeContentOperation(ctx.event, ctx.type.capabilities?.write)
+
+  const item = await requireContentAdapter().update(ctx, id, payload)
+
+  if (ctx.type.hooks?.afterUpdate) {
+    await ctx.type.hooks.afterUpdate(ctx, item, payload)
+  }
+
+  return item
+}
+
+/** Deletes one item. Authorizes against `type.capabilities.delete` before calling the adapter. */
+export async function deleteContentItem(ctx: PlutoContentContext, id: string | number): Promise<void> {
+  await authorizeContentOperation(ctx.event, ctx.type.capabilities?.delete)
+
+  await requireContentAdapter().remove(ctx, id)
+}

package/server/utils/pluto-content.ts

@@ -0,0 +1,44 @@
+/**
+ * The server-side content-type and adapter registry. Deliberately a plain
+ * module-scope singleton — NOT built like `usePlutoRegistry` (the client
+ * registry in `app/composables/pluto-registry.ts`), and that is on purpose,
+ * not an oversight.
+ *
+ * The client registry lives on `nuxtApp` instead of module scope because a
+ * module-scope object on the server would leak state between requests and
+ * between apps during SSR: one user's data could end up rendered into
+ * another user's response. That risk does not apply here, for three
+ * reasons:
+ *
+ * 1. Registration happens once, at Nitro startup, from a layer's own
+ *    `server/plugins/*.ts` file — not per request.
+ * 2. The registered values (`PlutoContentType`, `PlutoContentAdapter`) are
+ *    static definition objects. They hold zero per-request state.
+ * 3. Anything that actually varies per request — the caller's identity,
+ *    their session — travels in `PlutoContentContext.event`, which is
+ *    passed fresh into every adapter call. It never touches the registry.
+ *
+ * So a future reader who knows why the client registry avoids module scope
+ * should not assume the same warning applies here: it does not, because
+ * nothing stored here ever differs between two requests.
+ */
+
+const contentTypes = new Map<string, PlutoContentType>()
+let contentAdapter: PlutoContentAdapter | undefined
+
+export function registerContentType(type: PlutoContentType): void {
+  contentTypes.set(type.name, type)
+}
+
+export function getContentType(name: string): PlutoContentType | undefined {
+  return contentTypes.get(name)
+}
+
+/** Replaces whatever adapter was registered before. Last-registered wins, the same rule `mediaAdapters`/`settingsDrivers` use client-side. */
+export function registerContentAdapter(adapter: PlutoContentAdapter): void {
+  contentAdapter = adapter
+}
+
+export function getContentAdapter(): PlutoContentAdapter | undefined {
+  return contentAdapter
+}

package/shared/types/content.ts

@@ -0,0 +1,253 @@
+import type { H3Event } from 'h3'
+
+export type PlutoFieldType =
+  | 'text'
+  | 'textarea'
+  | 'richtext'
+  | 'slug'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'select'
+  | 'reference'
+  | 'media'
+
+/**
+ * Fields every `PlutoField` shares, regardless of `type`. A concrete field
+ * (`PlutoTextField`, `PlutoSlugField`, and so on) narrows `type` to one
+ * literal and adds its own type-specific options on top of this base.
+ */
+export interface PlutoFieldBase {
+  /** Field key. Used as the object key on a `PlutoContentItem`, and as the default storage column (see `fieldColumn` in `shared/utils/content-map.ts`). */
+  name: string
+  type: PlutoFieldType
+  label: string
+  description?: string
+  /** Storage column, when it differs from `name`. Falls back to `name` when unset. */
+  column?: string
+  required?: boolean
+  /** Show this field as a column in the generic list view. Default false. */
+  inList?: boolean
+  /** Show this field in the generic form view. Default true. */
+  inForm?: boolean
+  /** Lower comes first, in both the list and the form. Default 100. */
+  order?: number
+  default?: unknown
+  /** Name of a registered `PlutoContentFieldWidget` to force, overriding the default resolved by `type`. */
+  widget?: string
+  /** Which column of the generic form this field renders in. Default 'main'. */
+  region?: 'main' | 'side'
+}
+
+export interface PlutoTextField extends PlutoFieldBase {
+  type: 'text' | 'textarea' | 'richtext'
+  maxLength?: number
+  placeholder?: string
+}
+
+export interface PlutoSlugField extends PlutoFieldBase {
+  type: 'slug'
+  /** Name of the field this slug is generated from, for example 'title'. */
+  from?: string
+  preview?: string
+}
+
+export interface PlutoNumberField extends PlutoFieldBase {
+  type: 'number'
+  integer?: boolean
+  min?: number
+  max?: number
+}
+
+export interface PlutoSelectField extends PlutoFieldBase {
+  type: 'select'
+  options: Array<{
+    label: string
+    value: string | number
+  }>
+}
+
+export interface PlutoReferenceField extends PlutoFieldBase {
+  type: 'reference'
+  /** Name of the referenced content type, for example 'category'. */
+  target?: string
+  optionsUrl?: string
+  labelKey?: string
+  valueKey?: string
+}
+
+export interface PlutoMediaField extends PlutoFieldBase {
+  type: 'media'
+  multiple?: boolean
+}
+
+export interface PlutoBooleanField extends PlutoFieldBase {
+  type: 'boolean'
+}
+
+export interface PlutoDateField extends PlutoFieldBase {
+  type: 'date'
+}
+
+export type PlutoField =
+  | PlutoTextField
+  | PlutoSlugField
+  | PlutoNumberField
+  | PlutoSelectField
+  | PlutoReferenceField
+  | PlutoMediaField
+  | PlutoBooleanField
+  | PlutoDateField
+
+/**
+ * Capability keys a content-type adapter checks before it reads, writes, or
+ * deletes a row. Plain strings, not registered `PlutoCapability` entries —
+ * see the permissions skill for the format (`<namespace>:<action>`).
+ */
+export interface PlutoContentTypeCapabilities {
+  read?: string
+  write?: string
+  delete?: string
+}
+
+export interface PlutoContentStatus {
+  /** Storage column. Falls back to 'status' when unset. */
+  column?: string
+  values: Array<{
+    label: string
+    value: string
+  }>
+  default?: string
+  /** The `values[].value` that counts as published, for example 'published'. */
+  publishedValue?: string
+  publishedAtColumn?: string
+}
+
+export interface PlutoContentTimestamps {
+  /** Storage column, or `false` to disable this timestamp. Falls back to 'created_at' when unset. */
+  created?: string | false
+  /** Storage column, or `false` to disable this timestamp. Falls back to 'updated_at' when unset. */
+  updated?: string | false
+}
+
+export interface PlutoContentI18n {
+  /** Reserved for a future release. Only 'row' will ever be supported: one row per locale. Not implemented yet — declaring it costs nothing and avoids a breaking rename later. */
+  strategy: 'row'
+  localeColumn?: string
+  groupColumn?: string
+}
+
+/**
+ * The contract for one content type: what fields it has, where it is
+ * stored, and how the generic list/form UI (a later wave) should render it.
+ * A layer declares one of these per content type it owns, through
+ * `defineContentType`.
+ */
+export interface PlutoContentType {
+  /**
+   * The content type's own identifier, for example 'post'. Kept separate
+   * from a registered `PlutoContentTypeEntry.id` for the exact same reason
+   * `PlutoCapability.key` is kept separate from `id` (see
+   * `shared/types/registry.ts`): the registry rewrites `id` to
+   * `'<extensionId>:<id>'`, which would corrupt a name used in a URL path
+   * segment or as a lookup key. Always read `name` for the real content
+   * type identity, never the registry entry's `id`.
+   */
+  name: string
+  label: string
+  labelPlural: string
+  icon?: string
+  /** Table or view name this content type reads and writes. */
+  source: string
+  /** Storage column for the primary key. Falls back to 'id' when unset. */
+  primaryKey?: string
+  /** Name of the field shown as the row's title in lists and breadcrumbs. */
+  titleField: string
+  fields: PlutoField[]
+  /** Name of the field that holds the slug, or `false` to disable slugging entirely. */
+  slug?: {
+    field: string
+  } | false
+  /** `false` disables status/publish workflow entirely for this content type. */
+  status?: PlutoContentStatus | false
+  /** `false` disables created/updated timestamps entirely for this content type. */
+  timestamps?: PlutoContentTimestamps | false
+  capabilities?: PlutoContentTypeCapabilities
+  defaultSort?: {
+    field: string
+    direction: 'asc' | 'desc'
+  }
+  /** Whether a later wave should generate list/edit/create admin routes for this content type. */
+  autoRoutes?: boolean
+  /** Base admin path for generated routes, for example '/admin/posts'. Only meaningful when `autoRoutes` is true. */
+  basePath?: string
+  navOrder?: number
+  i18n?: PlutoContentI18n
+  /**
+   * Server-only lifecycle hooks, run by the generic write handlers
+   * (`server/utils/pluto-content-handlers.ts`) after the adapter call
+   * succeeds and before the response goes out. Lets a layer with extra
+   * logic around a write — for example `supabase-shop` reconciling
+   * `product_media` rows after a product write — hook in without a bespoke
+   * endpoint just for that, and without polluting the generic adapter
+   * contract with a per-layer concern.
+   */
+  hooks?: {
+    afterCreate?: (ctx: PlutoContentContext, item: PlutoContentItem, rawBody: Record<string, unknown>) => Promise<void> | void
+    afterUpdate?: (ctx: PlutoContentContext, item: PlutoContentItem, rawBody: Record<string, unknown>) => Promise<void> | void
+  }
+}
+
+/**
+ * One stored content row, keyed by field name (not column name — see
+ * `mapColumnsToFields` in `shared/utils/content-map.ts` for the
+ * column-to-field translation). Named `PlutoContentItem`, not
+ * `PlutoEntryRecord`, to avoid visual confusion with `PlutoEntry` (a
+ * registry bucket item, see `shared/types/registry.ts`) — this type has
+ * nothing to do with the registry.
+ */
+export type PlutoContentItem = Record<string, unknown> & {
+  id: string | number
+}
+
+/** Options for a generic list read. See `server/utils/pluto-content-handlers.ts`. */
+export interface PlutoContentQuery {
+  limit?: number
+  offset?: number
+  search?: string
+  sort?: {
+    field: string
+    direction: 'asc' | 'desc'
+  }
+  includeUnpublished?: boolean
+}
+
+export interface PlutoContentListResult {
+  data: PlutoContentItem[]
+  total?: number
+}
+
+/** Per-request context an adapter method receives: the H3 event, and the content type being read or written. */
+export interface PlutoContentContext {
+  event: H3Event
+  type: PlutoContentType
+}
+
+/**
+ * Lets a backend layer (`@plutocms/supabase`, and so on) plug its own
+ * storage into the generic content server routes, without core knowing
+ * which backend is in use — the same role `PlutoMediaAdapter` plays for
+ * media. Exactly one adapter is meaningful per app, registered through
+ * `registerContentAdapter` (see `server/utils/pluto-content.ts`).
+ */
+export interface PlutoContentAdapter {
+  id: string
+  list: (ctx: PlutoContentContext, query: PlutoContentQuery) => Promise<PlutoContentListResult>
+  get: (ctx: PlutoContentContext, idOrSlug: string | number) => Promise<PlutoContentItem | null>
+  create: (ctx: PlutoContentContext, values: Record<string, unknown>) => Promise<PlutoContentItem>
+  update: (ctx: PlutoContentContext, id: string | number, values: Record<string, unknown>) => Promise<PlutoContentItem>
+  remove: (ctx: PlutoContentContext, id: string | number) => Promise<void>
+  /** Throws when `event`'s caller does not hold `capability`. Optional — see the fail-open rule in the content-model skill. */
+  authorize?: (event: H3Event, capability: string) => Promise<void>
+  describe?: (ctx: PlutoContentContext) => Promise<string[] | null>
+}

package/shared/types/media.ts

@@ -0,0 +1,34 @@
+export interface PlutoMediaItem {
+  id: string
+  name: string
+  url: string
+  mimeType?: string
+  size?: number
+  alt?: string
+}
+
+export interface PlutoMediaListOptions {
+  limit?: number
+  offset?: number
+  search?: string
+}
+
+/**
+ * Lets a storage layer (Supabase Storage, S3, R2, local disk...) plug into
+ * one shared media picker UI and one `media` field widget, without core
+ * knowing which backend is in use. Exactly one adapter is registered per
+ * app — see the `mediaAdapters` registry bucket, which keeps only the
+ * last-registered one, the same "last wins" rule as `settingsDrivers`.
+ */
+export interface PlutoMediaAdapter {
+  id: string
+  list: (options: PlutoMediaListOptions) => Promise<{
+    data: PlutoMediaItem[]
+    total?: number
+  }>
+  upload: (file: File, meta?: {
+    alt?: string
+  }) => Promise<PlutoMediaItem>
+  remove: (id: string) => Promise<void>
+  getUrl: (id: string) => string
+}

package/shared/types/registry.ts

@@ -1,4 +1,6 @@
 import type { Component, ComputedRef } from 'vue'
+import type { PlutoContentType, PlutoFieldType } from './content'
+import type { PlutoMediaAdapter } from './media'
 
 export interface PlutoEntry {
   /** Unique inside this extension. Stored as `<extensionId>:<id>`. */
@@ -85,6 +87,32 @@ export interface PlutoPermissionsDriver extends PlutoEntry {
   load: () => Promise<string[]>
 }
 
+/**
+ * A content type a layer declares, wrapped for the registry. `type.name`
+ * is the content type's real identity — see the doc comment on
+ * `PlutoContentType.name` in `shared/types/content.ts` for why it is kept
+ * separate from this entry's `id`.
+ */
+export interface PlutoContentTypeEntry extends PlutoEntry {
+  type: PlutoContentType
+}
+
+/**
+ * A component that renders one field type, or one named `widget`, in the
+ * generic content form (a later wave). `fieldType` and `widget` are both
+ * optional so an entry can match by either — see
+ * `usePlutoContentFieldWidget` for the resolution order.
+ */
+export interface PlutoContentFieldWidget extends PlutoEntry {
+  fieldType?: PlutoFieldType
+  widget?: string
+  component: Component
+}
+
+export interface PlutoMediaAdapterEntry extends PlutoEntry {
+  adapter: PlutoMediaAdapter
+}
+
 export interface PlutoExtension {
   /** Layer name. Use the package's $meta.name, e.g. 'supabase-blog'. */
   id: string
@@ -97,6 +125,9 @@ export interface PlutoExtension {
   settingsDriver?: PlutoSettingsDriver
   capabilities?: PlutoCapability[]
   permissionsDriver?: PlutoPermissionsDriver
+  contentTypes?: PlutoContentTypeEntry[]
+  contentFieldWidgets?: PlutoContentFieldWidget[]
+  mediaAdapters?: PlutoMediaAdapterEntry[]
 }
 
 /**
@@ -121,4 +152,7 @@ export interface PlutoRegistry {
   dashboardWidgets: PlutoRegistryBucket<PlutoDashboardWidget>
   capabilities: PlutoRegistryBucket<PlutoCapability>
   permissionsDrivers: PlutoRegistryBucket<PlutoPermissionsDriver>
+  contentTypes: PlutoRegistryBucket<PlutoContentTypeEntry>
+  contentFieldWidgets: PlutoRegistryBucket<PlutoContentFieldWidget>
+  mediaAdapters: PlutoRegistryBucket<PlutoMediaAdapterEntry>
 }

package/shared/utils/content-map.ts

@@ -0,0 +1,49 @@
+/** Resolves the storage column for a field. Falls back to `field.name` when `field.column` is unset. */
+export function fieldColumn(field: PlutoField): string {
+  return field.column ?? field.name
+}
+
+/**
+ * Converts a field-keyed payload into a column-keyed one, for every field
+ * in `type.fields` present in `payload`. A field absent from `payload` is
+ * left out of the result, so a partial update payload stays partial after
+ * mapping. An adapter (a later wave) sends the result straight to its
+ * storage layer.
+ */
+export function mapFieldsToColumns(
+  type: PlutoContentType,
+  payload: Record<string, unknown>
+): Record<string, unknown> {
+  const columns: Record<string, unknown> = {}
+
+  for (const field of type.fields) {
+    if (Object.hasOwn(payload, field.name)) {
+      columns[fieldColumn(field)] = payload[field.name]
+    }
+  }
+
+  return columns
+}
+
+/**
+ * Converts a column-keyed row into a field-keyed `PlutoContentItem`, for
+ * every field in `type.fields`, plus the primary key column (`type.primaryKey`,
+ * default `'id'`) mapped to `item.id`. A column absent from `row` is left
+ * out of the result field.
+ */
+export function mapColumnsToFields(
+  type: PlutoContentType,
+  row: Record<string, unknown>
+): PlutoContentItem {
+  const primaryKey = type.primaryKey ?? 'id'
+  const item: Record<string, unknown> = { id: row[primaryKey] }
+
+  for (const field of type.fields) {
+    const column = fieldColumn(field)
+    if (Object.hasOwn(row, column)) {
+      item[field.name] = row[column]
+    }
+  }
+
+  return item as PlutoContentItem
+}

package/shared/utils/content-validate.ts

@@ -0,0 +1,100 @@
+export interface ContentValidationError {
+  field: string
+  message: string
+}
+
+/**
+ * Checks a field-keyed payload against a content type's field rules. Pure
+ * TypeScript, no I/O and no Nuxt/Vue dependency, so a server route (a later
+ * wave) and an app composable can both call it and get the same answer.
+ *
+ * Pass `{ partial: true }` for a partial update (for example a PATCH):
+ * a required field missing from `payload` entirely is not an error, because
+ * omitting a field is not the same as clearing it. A required field present
+ * in `payload` with an empty value is still an error, partial or not.
+ */
+export function validateContentPayload(
+  type: PlutoContentType,
+  payload: Record<string, unknown>,
+  options?: {
+    partial?: boolean
+  }
+): ContentValidationError[] {
+  const errors: ContentValidationError[] = []
+
+  for (const field of type.fields) {
+    const present = Object.hasOwn(payload, field.name)
+    const value = payload[field.name]
+
+    if (field.required) {
+      const skipBecausePartial = options?.partial === true && !present
+      const empty = value === undefined || value === null || value === ''
+      if (!skipBecausePartial && empty) {
+        errors.push({ field: field.name, message: `"${field.label}" is required.` })
+        continue
+      }
+    }
+
+    // Nothing more to check when the field was not supplied at all.
+    if (!present || value === undefined || value === null) {
+      continue
+    }
+
+    switch (field.type) {
+      case 'number': {
+        const numeric = typeof value === 'number' ? value : Number(value)
+        if ((typeof value !== 'number' && typeof value !== 'string') || Number.isNaN(numeric)) {
+          errors.push({ field: field.name, message: `"${field.label}" must be a number.` })
+          break
+        }
+        if (field.integer && !Number.isInteger(numeric)) {
+          errors.push({ field: field.name, message: `"${field.label}" must be an integer.` })
+        }
+        if (field.min !== undefined && numeric < field.min) {
+          errors.push({ field: field.name, message: `"${field.label}" must be at least ${field.min}.` })
+        }
+        if (field.max !== undefined && numeric > field.max) {
+          errors.push({ field: field.name, message: `"${field.label}" must be at most ${field.max}.` })
+        }
+        break
+      }
+
+      case 'boolean': {
+        if (typeof value !== 'boolean') {
+          errors.push({ field: field.name, message: `"${field.label}" must be a boolean.` })
+        }
+        break
+      }
+
+      case 'select': {
+        if (!field.options.some((option) => option.value === value)) {
+          errors.push({ field: field.name, message: `"${field.label}" must be one of the allowed options.` })
+        }
+        break
+      }
+
+      case 'text':
+      case 'textarea':
+      case 'richtext':
+      case 'slug': {
+        // Only PlutoTextField carries maxLength; PlutoSlugField never does,
+        // so the 'in' check both narrows the type and skips slug fields.
+        const maxLength = 'maxLength' in field ? field.maxLength : undefined
+        if (maxLength !== undefined && typeof value === 'string' && value.length > maxLength) {
+          errors.push({
+            field: field.name,
+            message: `"${field.label}" must be at most ${maxLength} characters.`,
+          })
+        }
+        break
+      }
+
+      // 'date' | 'reference' | 'media': no format check in this wave, only
+      // the required check above.
+      default:
+        break
+    }
+  }
+
+  return errors
+}

package/shared/utils/content.ts

@@ -0,0 +1,49 @@
+/**
+ * Declares a content type. This is an identity function: it returns `type`
+ * unchanged. Its only job is type inference at the call site — wrapping a
+ * content type literal in `defineContentType` lets TypeScript narrow each
+ * `PlutoField`'s `type` correctly — plus a handful of dev-only sanity
+ * checks below. This mirrors `definePlutoExtension`'s role: a thin, typed
+ * entry point, not a place that does real work.
+ *
+ * The checks only warn, and only in dev (`import.meta.dev` strips them
+ * from a production build). A content type with a typo still loads. The
+ * warning exists to catch the typo before it reaches a later wave's
+ * generic list/form UI or server adapter, where it would fail silently or
+ * confusingly instead.
+ */
+export function defineContentType(type: PlutoContentType): PlutoContentType {
+  if (import.meta.dev) {
+    const prefix = `[pluto] content type "${type.name}":`
+    const seen = new Set<string>()
+
+    for (const field of type.fields) {
+      if (seen.has(field.name)) {
+        console.warn(`${prefix} duplicate field name "${field.name}".`)
+      }
+      seen.add(field.name)
+
+      if (field.type === 'select' && field.options.length === 0) {
+        console.warn(`${prefix} select field "${field.name}" has no options.`)
+      }
+    }
+
+    if (!type.fields.some((field) => field.name === type.titleField)) {
+      console.warn(`${prefix} titleField "${type.titleField}" does not match any field.`)
+    }
+
+    if (type.slug) {
+      const slug = type.slug
+      const field = type.fields.find((candidate) => candidate.name === slug.field)
+      if (!field || field.type !== 'slug') {
+        console.warn(`${prefix} slug.field "${slug.field}" does not name a field of type "slug".`)
+      }
+    }
+
+    if (type.status && type.status.values.length === 0) {
+      console.warn(`${prefix} status has no values.`)
+    }
+  }
+
+  return type
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  define: {
+    'import.meta.dev': 'true',
+  },
+})