@ekrist1/vulse 0.1.6-alpha.3 → 0.1.7-alpha.4

package/src/core/blueprints/reflect-fields.ts

@@ -0,0 +1,305 @@
+import { z, type ZodTypeAny } from 'astro/zod'
+
+import type { Blueprint } from './types.js'
+import type {
+  FieldDefinition,
+  FieldUi,
+  NestedFieldDefinition,
+  ReplicatorSetDefinition,
+  SelectOption,
+} from './definition.js'
+import { nestedFieldToDescriptor } from './code-to-definition.js'
+import { normalizeSelectOptions } from './select-helpers.js'
+
+export type Widget =
+  | 'text'
+  | 'textarea'
+  | 'number'
+  | 'bool'
+  | 'date'
+  | 'enum'
+  | 'ref'
+  | 'entry'
+  | 'entries'
+  | 'link'
+  | 'media'
+  | 'blocks'
+  | 'object'
+  | 'repeater'
+  | 'grid'
+  | 'replicator'
+
+export interface FieldDescriptor {
+  path: string
+  widget: Widget
+  required: boolean
+  description?: string
+  blocksSets?: string[]
+  replicatorSets?: ReplicatorSetDefinition[]
+  label?: string
+  options?: string[]
+  selectOptions?: { key: string; label: string }[]
+  selectMultiple?: boolean
+  selectPlaceholder?: string
+  selectClearable?: boolean
+  refTarget?: string
+  entryCollections?: string[]
+  entriesCollections?: string[]
+  entriesMax?: number
+  linkCollections?: string[]
+  gridMinRows?: number
+  gridMaxRows?: number
+  gridMode?: 'table' | 'stacked'
+  gridAddLabel?: string
+  children?: FieldDescriptor[]
+  itemFields?: FieldDescriptor[]
+}
+
+interface ZodDef {
+  type: string
+  innerType?: ZodTypeAny
+  element?: ZodTypeAny
+  shape?: Record<string, ZodTypeAny>
+  entries?: Record<string, string>
+  checks?: unknown[]
+}
+
+function unwrap(sch: ZodTypeAny): ZodTypeAny {
+  let inner = sch
+  for (;;) {
+    const def = inner._def as ZodDef
+    if (def.type === 'optional' || def.type === 'default') {
+      inner = def.innerType!
+      continue
+    }
+    break
+  }
+  return inner
+}
+
+function maxLength(sch: ZodTypeAny): number | undefined {
+  const checks = (sch._def as ZodDef).checks ?? []
+  for (const check of checks) {
+    const zod = (check as { _zod?: { def?: { check?: string; maximum?: number } } })._zod
+    if (zod?.def?.check === 'max_length') return zod.def.maximum
+  }
+  return undefined
+}
+
+function parseEntriesTag(tag: string): { collections: string[]; max?: number } {
+  const rest = tag.slice('vulse:entries:'.length)
+  const lastColon = rest.lastIndexOf(':')
+  if (lastColon > 0) {
+    const maybeMax = Number(rest.slice(lastColon + 1))
+    if (!Number.isNaN(maybeMax) && String(maybeMax) === rest.slice(lastColon + 1)) {
+      return {
+        collections: rest.slice(0, lastColon).split(',').filter(Boolean),
+        max: maybeMax,
+      }
+    }
+  }
+  return { collections: rest.split(',').filter(Boolean) }
+}
+
+export function reflectFields(schema: z.ZodObject<any>): FieldDescriptor[] {
+  const shape = schema.shape as Record<string, ZodTypeAny>
+  return Object.entries(shape).map(([path, sch]) => describe(path, sch))
+}
+
+function describe(path: string, sch: ZodTypeAny): FieldDescriptor {
+  const tag = (sch.description ?? '') as string
+  const required = !sch.isOptional()
+
+  if (tag === 'vulse:media') return { path, widget: 'media', required }
+  if (tag.startsWith('vulse:ref:')) {
+    return { path, widget: 'ref', required, refTarget: tag.slice('vulse:ref:'.length) }
+  }
+  if (tag.startsWith('vulse:entry:')) {
+    return {
+      path,
+      widget: 'entry',
+      required,
+      entryCollections: tag.slice('vulse:entry:'.length).split(',').filter(Boolean),
+    }
+  }
+  if (tag.startsWith('vulse:entries:')) {
+    const parsed = parseEntriesTag(tag)
+    return {
+      path,
+      widget: 'entries',
+      required,
+      entriesCollections: parsed.collections,
+      ...(parsed.max !== undefined ? { entriesMax: parsed.max } : {}),
+    }
+  }
+  if (tag.startsWith('vulse:link')) {
+    const collections =
+      tag.length > 'vulse:link'.length
+        ? tag.slice('vulse:link:'.length).split(',').filter(Boolean)
+        : undefined
+    return {
+      path,
+      widget: 'link',
+      required,
+      ...(collections !== undefined ? { linkCollections: collections } : {}),
+    }
+  }
+
+  const inner = unwrap(sch)
+  const t = (inner._def as ZodDef).type
+
+  if (t === 'string') {
+    const max = maxLength(inner)
+    return { path, widget: max && max > 200 ? 'textarea' : 'text', required }
+  }
+  if (t === 'number') return { path, widget: 'number', required }
+  if (t === 'boolean') return { path, widget: 'bool', required }
+  if (t === 'date') return { path, widget: 'date', required }
+  if (t === 'enum') {
+    const entries = (inner._def as ZodDef).entries ?? {}
+    const keys = Object.keys(entries)
+    return {
+      path,
+      widget: 'enum',
+      required,
+      options: keys,
+      selectOptions: keys.map((key) => ({ key, label: key })),
+    }
+  }
+  if (t === 'object') {
+    return { path, widget: 'object', required, children: reflectFields(inner as z.ZodObject<any>) }
+  }
+  if (t === 'any' && (tag === 'vulse:blocks' || tag.startsWith('vulse:blocks:'))) {
+    return blocksDescriptor(path, required, tag)
+  }
+  if (t === 'array') {
+    if (tag === 'vulse:blocks' || tag.startsWith('vulse:blocks:') || path === 'body') {
+      return blocksDescriptor(path, required, tag || 'vulse:blocks')
+    }
+    const el = (inner._def as ZodDef).element!
+    if ((el._def as ZodDef).type === 'object') {
+      const itemFields = reflectFields(el as z.ZodObject<any>)
+      if (tag === 'vulse:grid') {
+        return { path, widget: 'grid', required, itemFields, gridMode: 'table' }
+      }
+      return { path, widget: 'repeater', required, itemFields }
+    }
+    if ((el._def as ZodDef).type === 'enum') {
+      const entries = (el._def as ZodDef).entries ?? {}
+      const keys = Object.keys(entries)
+      return {
+        path,
+        widget: 'enum',
+        required,
+        options: keys,
+        selectOptions: keys.map((key) => ({ key, label: key })),
+        selectMultiple: true,
+      }
+    }
+    return { path, widget: 'text', required }
+  }
+  return { path, widget: 'text', required }
+}
+
+const RESERVED_FIELD_NAMES = new Set(['slug', 'status', 'seo'])
+
+export function fieldDescriptorsFromDefinitions(fields: FieldDefinition[]): FieldDescriptor[] {
+  return fields.map(fieldDefinitionToDescriptor)
+}
+
+export function fieldDescriptorsFromBlueprint(bp: Blueprint): FieldDescriptor[] {
+  const all = !bp.fields?.length
+    ? reflectFields(bp.schema as z.ZodObject<any>)
+    : bp.fields.map(fieldDefinitionToDescriptor)
+  return all.filter((f) => !RESERVED_FIELD_NAMES.has(f.path))
+}
+
+function selectDescriptor(
+  base: { path: string; required: boolean; label?: string },
+  options: SelectOption[],
+  config?: { multiple?: boolean; placeholder?: string; clearable?: boolean },
+): FieldDescriptor {
+  const normalized = normalizeSelectOptions(options)
+  return {
+    ...base,
+    widget: 'enum',
+    options: normalized.map((o) => o.key),
+    selectOptions: normalized,
+    ...(config?.multiple !== undefined ? { selectMultiple: config.multiple } : {}),
+    ...(config?.placeholder !== undefined ? { selectPlaceholder: config.placeholder } : {}),
+    ...(config?.clearable !== undefined ? { selectClearable: config.clearable } : {}),
+  }
+}
+
+function fieldDefinitionToDescriptor(f: FieldDefinition): FieldDescriptor {
+  const base = { path: f.name, required: !f.optional, label: f.label ?? f.name }
+  switch (f.ui.kind) {
+    case 'textarea':
+      return { ...base, widget: 'textarea' }
+    case 'boolean':
+      return { ...base, widget: 'bool' }
+    case 'date':
+      return { ...base, widget: 'date' }
+    case 'select':
+      return selectDescriptor(base, f.ui.options, {
+        ...(f.ui.multiple !== undefined ? { multiple: f.ui.multiple } : {}),
+        ...(f.ui.placeholder !== undefined ? { placeholder: f.ui.placeholder } : {}),
+        ...(f.ui.clearable !== undefined ? { clearable: f.ui.clearable } : {}),
+      })
+    case 'relationship':
+      return { ...base, widget: 'ref', refTarget: f.ui.to }
+    case 'entry':
+      return { ...base, widget: 'entry', entryCollections: f.ui.collections }
+    case 'entries':
+      return {
+        ...base,
+        widget: 'entries',
+        entriesCollections: f.ui.collections,
+        ...(f.ui.max !== undefined ? { entriesMax: f.ui.max } : {}),
+      }
+    case 'link':
+      return {
+        ...base,
+        widget: 'link',
+        ...(f.ui.collections !== undefined ? { linkCollections: f.ui.collections } : {}),
+      }
+    case 'asset':
+      return { ...base, widget: 'media' }
+    case 'blocks': {
+      const tag = f.ui.sets?.length ? `vulse:blocks:${f.ui.sets.join(',')}` : 'vulse:blocks'
+      return {
+        ...base,
+        widget: 'blocks',
+        description: tag,
+        ...(f.ui.sets?.length ? { blocksSets: f.ui.sets } : {}),
+      }
+    }
+    case 'replicator':
+      return { ...base, widget: 'replicator', replicatorSets: f.ui.sets }
+    case 'grid':
+      return {
+        ...base,
+        widget: 'grid',
+        itemFields: f.ui.fields.map((field) => nestedFieldToDescriptor(field)),
+        gridMode: f.ui.mode ?? 'table',
+        ...(f.ui.minRows !== undefined ? { gridMinRows: f.ui.minRows } : {}),
+        ...(f.ui.maxRows !== undefined ? { gridMaxRows: f.ui.maxRows } : {}),
+        ...(f.ui.addLabel !== undefined ? { gridAddLabel: f.ui.addLabel } : {}),
+      }
+    default:
+      return { ...base, widget: 'text' }
+  }
+}
+
+function blocksDescriptor(path: string, required: boolean, tag: string): FieldDescriptor {
+  const blocksSets = tag.startsWith('vulse:blocks:')
+    ? tag.slice('vulse:blocks:'.length).split(',').filter(Boolean)
+    : []
+  return {
+    path,
+    widget: 'blocks',
+    required,
+    description: tag,
+    ...(blocksSets.length ? { blocksSets } : {}),
+  }
+}

package/src/core/blueprints/registry.ts

@@ -0,0 +1,14 @@
+import type { Blueprint } from './types.js'
+
+export class BlueprintRegistry {
+  #map = new Map<string, Blueprint>()
+
+  register(bp: Blueprint): void {
+    if (this.#map.has(bp.name)) throw new Error(`Blueprint "${bp.name}" already registered`)
+    this.#map.set(bp.name, bp)
+  }
+
+  get(name: string): Blueprint | undefined { return this.#map.get(name) }
+  list(): Blueprint[] { return [...this.#map.values()] }
+  has(name: string): boolean { return this.#map.has(name) }
+}

package/src/core/blueprints/seed.ts

@@ -0,0 +1,20 @@
+import { eq } from 'drizzle-orm'
+import type { VulseDb } from '../db.js'
+import { vulseCollections } from '../schema.js'
+import { createBlueprint, getBlueprintDefinition } from './mutations.js'
+import { blueprintToDefinition } from './code-to-definition.js'
+import type { Blueprint } from './types.js'
+
+export async function seedCodeBlueprints(db: VulseDb, codeBlueprints: Blueprint[]): Promise<void> {
+  for (const bp of codeBlueprints) {
+    const existing = await getBlueprintDefinition(db, bp.name)
+    if (existing) continue
+    const def = blueprintToDefinition(bp)
+    await createBlueprint(db, def)
+  }
+}
+
+export async function listCollectionHandles(db: VulseDb): Promise<string[]> {
+  const rows = await db.select({ handle: vulseCollections.handle }).from(vulseCollections)
+  return rows.map((r) => r.handle)
+}

package/src/core/blueprints/select-helpers.ts

@@ -0,0 +1,30 @@
+import type { SelectOption } from './definition.js'
+
+export function normalizeSelectOptions(options: SelectOption[]): { key: string; label: string }[] {
+  return options.map((o) => (typeof o === 'string' ? { key: o, label: o } : o))
+}
+
+export function selectOptionKeys(options: SelectOption[]): [string, ...string[]] {
+  const keys = normalizeSelectOptions(options).map((o) => o.key)
+  if (keys.length === 0) throw new Error('Select field requires at least one option')
+  return keys as [string, ...string[]]
+}
+
+/** Parse blueprint editor textarea: `key` or `key: Label` per line. */
+export function parseSelectOptionsText(text: string): SelectOption[] {
+  return text
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const colon = line.indexOf(':')
+      if (colon > 0) {
+        return { key: line.slice(0, colon).trim(), label: line.slice(colon + 1).trim() }
+      }
+      return line
+    })
+}
+
+export function formatSelectOptionsText(options: SelectOption[]): string {
+  return options.map((o) => (typeof o === 'string' ? o : `${o.key}: ${o.label}`)).join('\n')
+}

package/src/core/blueprints/seo.ts

@@ -0,0 +1,180 @@
+import { z } from 'astro/zod'
+import type { FieldDescriptor } from './reflect-fields.js'
+
+export const SEO_FIELD_PATH = 'seo'
+
+export interface SeoContent {
+  metaTitle?: string
+  metaDescription?: string
+  ogImage?: string
+}
+
+/** Maps blueprint content fields to SEO defaults. Omitted keys use inferred defaults. */
+export interface SeoFieldMapping {
+  metaTitle?: string
+  metaDescription?: string
+  ogImage?: string
+}
+
+export const SeoFieldMappingSchema = z.object({
+  metaTitle: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/).optional(),
+  metaDescription: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/).optional(),
+  ogImage: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/).optional(),
+})
+
+export interface ResolvedSeoField<T = string> {
+  value: T | undefined
+  sourceField?: string
+  overridden: boolean
+}
+
+export interface ResolvedSeo {
+  metaTitle: ResolvedSeoField
+  metaDescription: ResolvedSeoField
+  ogImage: ResolvedSeoField
+}
+
+interface BlockNode {
+  type?: string
+  text?: string
+  content?: BlockNode[]
+}
+
+export function seoZodSchema(): z.ZodOptional<z.ZodObject<{
+  metaTitle: z.ZodOptional<z.ZodString>
+  metaDescription: z.ZodOptional<z.ZodString>
+  ogImage: z.ZodOptional<z.ZodString>
+}>> {
+  return z.object({
+    metaTitle: z.string().max(70).optional(),
+    metaDescription: z.string().max(160).optional(),
+    ogImage: z.string().describe('vulse:media').optional(),
+  }).optional()
+}
+
+export function applySeoToSchema(
+  schema: z.ZodObject<z.ZodRawShape>,
+  seo?: boolean,
+): z.ZodObject<z.ZodRawShape> {
+  if (!seo) return schema
+  if (SEO_FIELD_PATH in schema.shape) return schema
+  return z.object({
+    ...schema.shape,
+    [SEO_FIELD_PATH]: seoZodSchema(),
+  })
+}
+
+export function emptySeoContent(): SeoContent {
+  return {}
+}
+
+function isProseMirrorDoc(v: unknown): v is BlockNode {
+  return typeof v === 'object' && v !== null && (v as BlockNode).type === 'doc'
+}
+
+function plainTextFromRichContent(value: unknown): string {
+  if (typeof value === 'string') return value.replace(/\s+/g, ' ').trim()
+  if (!isProseMirrorDoc(value)) return ''
+  const parts: string[] = []
+  function walk(nodes: BlockNode[] | undefined) {
+    for (const node of nodes ?? []) {
+      if (node.type === 'text') parts.push(node.text ?? '')
+      else walk(node.content)
+    }
+  }
+  walk(value.content)
+  return parts.join(' ').replace(/\s+/g, ' ').trim()
+}
+
+function truncateDescription(text: string, max = 160): string {
+  if (text.length <= max) return text
+  const slice = text.slice(0, max)
+  const lastSpace = slice.lastIndexOf(' ')
+  return (lastSpace > 0 ? slice.slice(0, lastSpace) : slice).trim()
+}
+
+export function resolveSeoFieldMapping(
+  fields: Array<Pick<FieldDescriptor, 'path' | 'widget'>>,
+  titleField: string,
+  mapping?: SeoFieldMapping,
+): SeoFieldMapping {
+  const mediaField = fields.find((f) => f.widget === 'media')?.path
+  const textareaField = fields.find((f) => f.widget === 'textarea')?.path
+  const blocksField = fields.find((f) => f.widget === 'blocks')?.path
+  const textField = fields.find((f) => f.widget === 'text' && f.path !== titleField)?.path
+
+  const resolved: SeoFieldMapping = {
+    metaTitle: mapping?.metaTitle ?? titleField,
+  }
+  const metaDescription = mapping?.metaDescription ?? textareaField ?? blocksField ?? textField
+  if (metaDescription) resolved.metaDescription = metaDescription
+  const ogImage = mapping?.ogImage ?? mediaField
+  if (ogImage) resolved.ogImage = ogImage
+  return resolved
+}
+
+export function extractSeoFieldValue(
+  value: unknown,
+  widget: FieldDescriptor['widget'] | undefined,
+): string | undefined {
+  if (value === null || value === undefined) return undefined
+  switch (widget) {
+    case 'media':
+      return typeof value === 'string' && value ? value : undefined
+    case 'textarea':
+    case 'text':
+      return typeof value === 'string' && value.trim() ? value.trim() : undefined
+    case 'blocks':
+      return plainTextFromRichContent(value) || undefined
+    default:
+      if (typeof value === 'string' && value.trim()) return value.trim()
+      return undefined
+  }
+}
+
+export function resolveEffectiveSeo(
+  content: Record<string, unknown>,
+  explicit: SeoContent | undefined,
+  fields: FieldDescriptor[],
+  titleField: string,
+  mapping?: SeoFieldMapping,
+): ResolvedSeo {
+  const fieldByPath = new Map(fields.map((f) => [f.path, f]))
+  const resolvedMapping = resolveSeoFieldMapping(fields, titleField, mapping)
+
+  function resolveField(
+    key: keyof SeoContent,
+    mapKey: keyof SeoFieldMapping,
+    transform?: (value: string) => string,
+  ): ResolvedSeoField {
+    const rawOverride = explicit?.[key]
+    if (key === 'ogImage') {
+      if (typeof rawOverride === 'string' && rawOverride) {
+        return { value: rawOverride, overridden: true }
+      }
+    } else if (typeof rawOverride === 'string' && rawOverride.trim()) {
+      return { value: rawOverride.trim(), overridden: true }
+    }
+    const sourceField = resolvedMapping[mapKey]
+    if (!sourceField) return { value: undefined, overridden: false }
+    const widget = fieldByPath.get(sourceField)?.widget
+    const raw = extractSeoFieldValue(content[sourceField], widget)
+    const value = raw && transform ? transform(raw) : raw
+    return { value, sourceField, overridden: false }
+  }
+
+  return {
+    metaTitle: resolveField('metaTitle', 'metaTitle'),
+    metaDescription: resolveField('metaDescription', 'metaDescription', truncateDescription),
+    ogImage: resolveField('ogImage', 'ogImage'),
+  }
+}
+
+export function resolvedSeoSummary(resolved: ResolvedSeo): string {
+  const title = resolved.metaTitle.value?.trim()
+  if (title) return title
+  const description = resolved.metaDescription.value?.trim()
+  if (description) return truncateDescription(description, 70)
+  if (resolved.ogImage.value) return 'Image configured'
+  return 'No defaults available yet'
+}

package/src/core/blueprints/types.ts

@@ -0,0 +1,59 @@
+import type { z } from 'astro/zod'
+import type { BlueprintDefinition, FieldDefinition } from './definition.js'
+
+export type Role = 'admin' | 'editor' | 'member'
+
+export interface AuthContext {
+  user: { id: string; role: Role; email: string } | null
+}
+
+export interface AccessArgs<T = unknown> extends AuthContext {
+  entry?: { id: string; status: 'draft' | 'published'; createdBy: string | null; content: T }
+}
+
+export type AccessFn<T = unknown> = (args: AccessArgs<T>) => boolean | Promise<boolean>
+
+import type { SeoFieldMapping } from './seo.js'
+
+export interface AdminConfig {
+  titleField: string
+  listColumns?: string[]
+  /** Maps content fields to SEO defaults in the entry editor. */
+  seoMapping?: SeoFieldMapping
+}
+
+export interface PreviewConfig {
+  /**
+   * URL template for the public-facing entry page. `{slug}` is replaced with
+   * the entry's URL slug. Defaults to `/{slug}` if omitted.
+   * Example: `/recipes/{slug}` or `/blog/{slug}`.
+   */
+  path: string
+  /** DOM selector for live preview morph target. Defaults to `main`. */
+  rootSelector?: string
+  /** When `false`, hides the live preview split panel (Preview button still works). Defaults to `true`. */
+  live?: boolean
+}
+
+export interface BlueprintAccess<T = unknown> {
+  read?: AccessFn<T>
+  create?: AccessFn<T>
+  update?: AccessFn<T>
+  delete?: AccessFn<T>
+}
+
+export interface Blueprint<S extends z.ZodTypeAny = z.ZodTypeAny> {
+  name: string
+  label: string
+  schema: S
+  admin: AdminConfig
+  access?: BlueprintAccess<z.infer<S>>
+  preview?: PreviewConfig
+  singleton?: boolean
+  tree?: boolean
+  maxDepth?: number
+  drafts?: boolean
+  seo?: boolean
+  fields?: FieldDefinition[]
+  definition?: BlueprintDefinition
+}

package/src/core/blueprints/zod-helpers.ts

@@ -0,0 +1,86 @@
+import { z as astroZ, type ZodRawShape, type ZodTypeAny } from 'astro/zod'
+import { blockSchema } from '../blocks/schema.js'
+import { LinkValueSchema } from './definition.js'
+
+export const EMPTY_BLOCKS_DOC = {
+  type: 'doc',
+  content: [{ type: 'paragraph' }],
+} as const
+
+export function blocks(sets?: string[]) {
+  const tag = sets?.length ? `vulse:blocks:${sets.join(',')}` : 'vulse:blocks'
+  return astroZ.any().default(EMPTY_BLOCKS_DOC).describe(tag)
+}
+
+/** Legacy flat block list (deprecated). */
+export function blocksLegacy() {
+  return astroZ.array(blockSchema).default([]).describe('vulse:blocks-legacy')
+}
+
+/** Media reference: stored as the media row's id; resolved at read time. */
+export function media() {
+  return astroZ.string().min(1).describe('vulse:media')
+}
+
+/** Reference to another collection (or 'user'). Kept for backward compatibility. */
+export function ref(target: string) {
+  return astroZ.string().min(1).describe(`vulse:ref:${target}`)
+}
+
+/** Single entry picker from one or more collections. */
+export function entry(...collections: string[]) {
+  if (collections.length === 0) throw new Error('entry() requires at least one collection')
+  return astroZ.string().min(1).describe(`vulse:entry:${collections.join(',')}`)
+}
+
+/** Multi-entry picker from one or more collections. */
+export function entries(collections: string[], max?: number) {
+  if (collections.length === 0) throw new Error('entries() requires at least one collection')
+  let schema = astroZ.array(astroZ.string().min(1))
+  if (max !== undefined) schema = schema.max(max)
+  const tag =
+    max !== undefined
+      ? `vulse:entries:${collections.join(',')}:${max}`
+      : `vulse:entries:${collections.join(',')}`
+  return schema.describe(tag)
+}
+
+/** URL, entry, or first-child link value. */
+export function link(collections?: string[]) {
+  const tag = collections?.length ? `vulse:link:${collections.join(',')}` : 'vulse:link'
+  return LinkValueSchema.describe(tag)
+}
+
+/** Homogeneous row grid (array of objects with fixed columns). */
+export function grid<T extends ZodRawShape>(
+  fields: T,
+  opts?: { minRows?: number; maxRows?: number },
+) {
+  let schema = astroZ.array(astroZ.object(fields))
+  if (opts?.minRows !== undefined) schema = schema.min(opts.minRows)
+  if (opts?.maxRows !== undefined) schema = schema.max(opts.maxRows)
+  return schema.describe('vulse:grid')
+}
+
+export type VulseZ = typeof astroZ & {
+  media: typeof media
+  ref: typeof ref
+  entry: typeof entry
+  entries: typeof entries
+  link: typeof link
+  grid: typeof grid
+}
+
+export const z: VulseZ = new Proxy(astroZ, {
+  get(target, prop, receiver) {
+    if (prop === 'media') return media
+    if (prop === 'ref') return ref
+    if (prop === 'entry') return entry
+    if (prop === 'entries') return entries
+    if (prop === 'link') return link
+    if (prop === 'grid') return grid
+    return Reflect.get(target, prop, receiver)
+  },
+}) as VulseZ
+
+export type { ZodTypeAny }