@stacksjs/defaults 0.70.380 → 0.71.2

package/resources/functions/dashboard/sidebar.ts

@@ -6,6 +6,7 @@
  * persistence stay inside the component instead of being serialized as HTML.
  */
 import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { resolve } from 'node:path'
 
 type ModelCategory = 'userland' | 'data' | 'commerce' | 'content' | 'marketing' | 'system'
@@ -57,9 +58,24 @@ export interface DashboardSectionToggles {
   data: DataRowToggles
 }
 
+/** An application-defined sidebar row, from `config/dashboard.ts:nav`. */
+export interface AppNavItem {
+  label: string
+  href: string
+  icon?: string
+  roles?: string[]
+}
+
+export interface AppNavSection {
+  title: string
+  items: AppNavItem[]
+}
+
 export interface DiscoveredManifest {
   models: DiscoveredModel[]
   sections: DashboardSectionToggles
+  /** Sections this application declared. Empty for a project that declared none. */
+  nav: AppNavSection[]
 }
 
 export const DEFAULT_DATA_TOGGLES: DataRowToggles = {
@@ -103,7 +119,7 @@ export function loadDiscoveredManifest(
   manifestPath = resolve(process.cwd(), 'storage/framework/defaults/views/dashboard/.discovered-models.json'),
 ): DiscoveredManifest {
   if (!existsSync(manifestPath))
-    return { models: [], sections: defaultToggles() }
+    return { models: [], sections: defaultToggles(), nav: [] }
 
   try {
     return parseDiscoveredManifest(readFileSync(manifestPath, 'utf8'))
@@ -138,9 +154,35 @@ export function parseDiscoveredManifest(source: string): DiscoveredManifest {
   return {
     models,
     sections: normalizeManifestToggles(envelope.sections),
+    nav: normalizeManifestNav(envelope.nav),
   }
 }
 
+/**
+ * App-declared sections are validated at config load; this only has to survive
+ * a manifest written by an older framework version, which has no `nav` key.
+ */
+function normalizeManifestNav(value: unknown): AppNavSection[] {
+  if (value === undefined)
+    return []
+
+  if (!Array.isArray(value))
+    throw new TypeError('manifest nav must be an array')
+
+  return value.map((entry, index) => {
+    const section = objectValue(entry, `manifest nav[${index}]`)
+    if (typeof section.title !== 'string' || !section.title)
+      throw new TypeError(`manifest nav[${index}].title must be a non-empty string`)
+    if (!Array.isArray(section.items))
+      throw new TypeError(`manifest nav[${index}].items must be an array`)
+
+    return {
+      title: section.title,
+      items: section.items as AppNavItem[],
+    }
+  })
+}
+
 function normalizeManifestToggles(value: unknown): DashboardSectionToggles {
   const sections = objectValue(value, 'manifest sections')
   const data = sections.data === undefined
@@ -241,9 +283,25 @@ function categoryNavItems(
 export function buildNavSections(
   discoveredModels: DiscoveredModel[] = [],
   toggles: DashboardSectionToggles = DEFAULT_TOGGLES,
+  appNav: AppNavSection[] = [],
 ): Array<[string, string, NavItem[]]> {
   const sections: Array<[string, string, NavItem[]]> = []
 
+  // Application sections come first. An app that declares its own pages is
+  // saying those are the product; the framework's operational surfaces
+  // (queue, logs, deployments) are support and belong below them.
+  for (const [index, section] of appNav.entries()) {
+    if (section.items.length === 0)
+      continue
+
+    sections.push([`app-nav-${index}`, section.title, section.items.map(item => ({
+      to: item.href,
+      icon: item.icon ?? 'circle',
+      text: item.label,
+      ...(item.roles && item.roles.length > 0 ? { roles: item.roles } : {}),
+    }))])
+  }
+
   // Library section: the established views live at the project root
   // (`/functions`, `/packages`, `/releases`). Components use the explicit
   // `/library/components` path so it does not collide with STX's component
@@ -549,9 +607,57 @@ function titleCase(label: string): string {
  * discovered-models manifest synchronously (stx server-script friendly)
  * and applies the shared section and toggle logic.
  */
+/**
+ * Framework sections name their icons from the map above. App-declared rows
+ * may instead give a full iconify class, which is passed through untouched -
+ * an application should not be limited to the icons the framework happened to
+ * name, and `i-hugeicons-champion` is the spelling its own templates use.
+ */
+function resolveNavIcon(icon: string): string {
+  if (icon.startsWith('i-'))
+    return icon
+
+  return NAV_ICON_CLASSES[icon] ?? NAV_ICON_CLASSES.file!
+}
+
+/**
+ * Read app-declared sections straight from `config/dashboard.ts`.
+ *
+ * The manifest is the primary source, but it is written by the dashboard dev
+ * command - so an app running a published framework older than the `nav` key
+ * would get a manifest without one, and its own pages would stay unreachable.
+ * Reading the config directly also means editing it shows up on the next
+ * reload rather than on the next manifest write.
+ *
+ * `require` rather than `import`: this module is called synchronously from STX
+ * server-script context, and Bun transpiles the TS config on the way in.
+ */
+function loadAppNavFromConfig(configPath = resolve(process.cwd(), 'config/dashboard.ts')): AppNavSection[] {
+  if (!existsSync(configPath))
+    return []
+
+  let config: unknown
+  try {
+    const requireFrom = createRequire(import.meta.url)
+    const loaded = requireFrom(configPath) as { default?: unknown }
+    config = loaded?.default ?? loaded
+  }
+  catch {
+    // An unreadable config is the dashboard's problem elsewhere, not the
+    // sidebar's: fall back to the framework sections rather than blanking the
+    // whole navigation.
+    return []
+  }
+
+  // Validation deliberately outside the catch - a malformed `nav` is an
+  // authoring mistake and should say so, not silently render nothing.
+  return normalizeManifestNav((config as { nav?: unknown } | undefined)?.nav)
+}
+
 export function buildWebSidebarSections(): WebSidebarSection[] {
   const manifest = loadDiscoveredManifest()
-  const sections = buildNavSections(manifest.models, manifest.sections)
+  const appNav = manifest.nav.length > 0 ? manifest.nav : loadAppNavFromConfig()
+  const sections = buildNavSections(manifest.models, manifest.sections, appNav)
 
   return [
     {
@@ -565,7 +671,7 @@ export function buildWebSidebarSections(): WebSidebarSection[] {
       items: items.map(item => ({
         id: navItemId(item.to),
         label: item.text,
-        icon: NAV_ICON_CLASSES[item.icon] ?? NAV_ICON_CLASSES.file,
+        icon: resolveNavIcon(item.icon),
         iconColor: 'blue',
         href: item.to,
         ...(item.roles && item.roles.length > 0 ? { roles: item.roles } : {}),

package/resources/functions/dashboard/toggles.ts

@@ -10,6 +10,29 @@ export interface DashboardDataRowToggles {
   allModels: boolean
 }
 
+/**
+ * One row of an application-defined sidebar section.
+ *
+ * `icon` is either a full iconify class (`i-hugeicons-calendar-03`), which is
+ * passed through as written, or one of the framework's own short sidebar icon
+ * names (`calendar`, `bell`, `chart`), which resolves through its icon map.
+ * The first form is what an app wants: it is the same spelling every template
+ * in the project already uses, and it is not limited to the set the framework
+ * happens to have named.
+ */
+export interface DashboardNavItem {
+  label: string
+  href: string
+  icon?: string
+  /** Role gate, matching the per-model `dashboard.roles` metadata. */
+  roles?: string[]
+}
+
+export interface DashboardNavSection {
+  title: string
+  items: DashboardNavItem[]
+}
+
 export interface ResolvedDashboardToggles {
   library: boolean
   content: boolean
@@ -73,14 +96,79 @@ export function resolveDashboardToggles(value: unknown): ResolvedDashboardToggle
 }
 
 export async function loadDashboardToggles(configPath: string): Promise<ResolvedDashboardToggles> {
+  return (await loadDashboardConfig(configPath)).toggles
+}
+
+/**
+ * Application-defined sidebar sections from `config/dashboard.ts:nav`.
+ *
+ * The framework's own sections are a fixed list, so before this an app that
+ * added dashboard pages under `resources/views/dashboard/` had pages the
+ * sidebar could not reach - the pages worked, but only if you typed the URL.
+ * Declaring them in config keeps the sidebar in one place and out of the
+ * framework's own registry, which an app cannot edit without vendoring it.
+ */
+export function resolveDashboardNav(value: unknown): DashboardNavSection[] {
+  if (!value || typeof value !== 'object')
+    return []
+
+  const config = value as Record<string, unknown>
+  if (config.nav === undefined)
+    return []
+
+  if (!Array.isArray(config.nav))
+    throw new TypeError('dashboard config nav must be an array of sections')
+
+  return config.nav.map((entry, index) => {
+    const section = objectValue(entry, `dashboard config nav[${index}]`)
+    if (typeof section.title !== 'string' || !section.title)
+      throw new TypeError(`dashboard config nav[${index}].title must be a non-empty string`)
+    if (!Array.isArray(section.items))
+      throw new TypeError(`dashboard config nav[${index}].items must be an array`)
+
+    return {
+      title: section.title,
+      items: section.items.map((value, itemIndex) => {
+        const label = `dashboard config nav[${index}].items[${itemIndex}]`
+        const item = objectValue(value, label)
+        if (typeof item.label !== 'string' || !item.label)
+          throw new TypeError(`${label}.label must be a non-empty string`)
+        if (typeof item.href !== 'string' || !item.href)
+          throw new TypeError(`${label}.href must be a non-empty string`)
+
+        return {
+          label: item.label,
+          href: item.href,
+          icon: typeof item.icon === 'string' ? item.icon : undefined,
+          roles: Array.isArray(item.roles) ? item.roles.map(String) : undefined,
+        }
+      }),
+    }
+  })
+}
+
+export interface LoadedDashboardConfig {
+  toggles: ResolvedDashboardToggles
+  nav: DashboardNavSection[]
+}
+
+/**
+ * Read `config/dashboard.ts` once and return everything the sidebar needs.
+ * One import rather than two: the config module is cache-busted on mtime, so a
+ * second load of the same file would be a second evaluation of user code.
+ */
+export async function loadDashboardConfig(configPath: string): Promise<LoadedDashboardConfig> {
   if (!existsSync(configPath))
-    return defaultDashboardToggles()
+    return { toggles: defaultDashboardToggles(), nav: [] }
 
   try {
     const moduleUrl = pathToFileURL(configPath)
     moduleUrl.searchParams.set('dashboard-config-mtime', String(statSync(configPath).mtimeMs))
     const configModule = await import(moduleUrl.href) as { default?: unknown }
-    return resolveDashboardToggles(configModule.default)
+    return {
+      toggles: resolveDashboardToggles(configModule.default),
+      nav: resolveDashboardNav(configModule.default),
+    }
   }
   catch (error) {
     throw new Error(`Could not load config/dashboard.ts: ${error instanceof Error ? error.message : String(error)}`)

package/resources/views/cms/blocks/columns.stx

@@ -0,0 +1,10 @@
+{{-- Columns block: 1-4 sanitized HTML columns on a responsive grid. --}}
+<div class="cms-columns mx-auto max-w-6xl px-6 py-8">
+  {{-- Literal class names, not `md:grid-cols-{{ n }}`: Crosswind extracts
+       classes from template SOURCE, so a composed name generates no CSS. --}}
+  <div class="grid grid-cols-1 gap-8 {{ props.columns.length === 4 ? 'md:grid-cols-4' : (props.columns.length === 3 ? 'md:grid-cols-3' : (props.columns.length === 2 ? 'md:grid-cols-2' : '')) }}">
+    @foreach (props.columns as column)
+      <div class="leading-relaxed">{!! column.html !!}</div>
+    @endforeach
+  </div>
+</div>

package/resources/views/cms/blocks/cta.stx

@@ -0,0 +1,8 @@
+{{-- Call-to-action band. --}}
+<section class="cms-cta mx-auto max-w-4xl px-6 py-16 text-center">
+  <h2 class="text-3xl tracking-tight font-semibold">{{ props.heading }}</h2>
+  @if (props.body)
+    <p class="mt-4 text-lg text-gray-600 max-w-[65ch] mx-auto">{{ props.body }}</p>
+  @endif
+  <a href="{{ props.buttonHref }}" class="mt-8 inline-block rounded-lg px-6 py-3 font-medium bg-gray-900 text-white transition-transform active:scale-[0.98]">{{ props.buttonLabel }}</a>
+</section>

package/resources/views/cms/blocks/embed.stx

@@ -0,0 +1,14 @@
+{{-- Embed block: sandboxed iframe, never inline third-party markup. --}}
+<div class="cms-embed mx-auto max-w-4xl px-6 py-8">
+  <div class="relative w-full overflow-hidden rounded-lg {{ props.aspect === '4:3' ? 'aspect-[4/3]' : (props.aspect === '1:1' ? 'aspect-square' : 'aspect-video') }}">
+    <iframe
+      src="{{ props.src }}"
+      title="{{ props.title }}"
+      class="absolute inset-0 h-full w-full"
+      sandbox="allow-scripts allow-same-origin allow-presentation"
+      referrerpolicy="no-referrer"
+      loading="lazy"
+      allowfullscreen
+    ></iframe>
+  </div>
+</div>

package/resources/views/cms/blocks/form.stx

@@ -0,0 +1,132 @@
+{{--
+  Form block: renders a @stacksjs/forms form inline on a CMS page.
+  `props.formUuid` names the form; the client script fetches the public
+  definition (same-origin), renders the fields, evaluates conditions live,
+  and submits with the CSRF header the page response seeded.
+--}}
+<div class="cms-form mx-auto max-w-xl px-6 py-8" data-form-uuid="{{ props.formUuid }}">
+  <script client>
+  const host = useRef('host')
+  const definition = state(null)
+  const values = reactive({})
+  const errors = state({})
+  const sending = state(false)
+  const done = state('')
+  const openedAt = Date.now()
+
+  effect(() => {
+    if (!host() || definition())
+      return
+    const uuid = host().dataset.formUuid
+    if (!uuid)
+      return
+    fetch(`/api/forms/${uuid}`, { credentials: 'same-origin' })
+      .then(reply => reply.ok ? reply.json() : null)
+      .then((body) => { if (body) definition.set(body) })
+      .catch(() => {})
+  })
+
+  function fieldVisible(field) {
+    const conditions = field.conditions
+    if (!conditions || !conditions.rules || conditions.rules.length === 0)
+      return true
+    const results = conditions.rules.map((rule) => {
+      const actual = values[rule.field]
+      switch (rule.op) {
+        case 'eq': return String(actual ?? '') === String(rule.value ?? '')
+        case 'neq': return String(actual ?? '') !== String(rule.value ?? '')
+        case 'contains': return String(actual ?? '').includes(String(rule.value ?? ''))
+        case 'gt': return Number(actual) > Number(rule.value)
+        case 'lt': return Number(actual) < Number(rule.value)
+        case 'empty': return actual === undefined || actual === null || String(actual) === ''
+        case 'not_empty': return actual !== undefined && actual !== null && String(actual) !== ''
+        default: return false
+      }
+    })
+    const matched = conditions.logic === 'all' ? results.every(Boolean) : results.some(Boolean)
+    return conditions.action === 'show' ? matched : !matched
+  }
+
+  async function submit(event) {
+    event.preventDefault()
+    if (sending())
+      return
+    sending.set(true)
+    errors.set({})
+
+    try {
+      const uuid = host().dataset.formUuid
+      const reply = await fetch(`/api/forms/${uuid}/submissions`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'same-origin',
+        body: JSON.stringify({ ...values, _renderedMs: Date.now() - openedAt }),
+      })
+      const body = await reply.json().catch(() => ({}))
+
+      if (reply.status === 422) {
+        errors.set(body.errors ?? {})
+        return
+      }
+      if (!reply.ok) {
+        errors.set({ _form: body.message ?? 'Something went wrong. Please try again.' })
+        return
+      }
+      if (body.redirect) {
+        navigate(body.redirect)
+        return
+      }
+      done.set(body.message ?? 'Thanks - your response was received.')
+    }
+    catch {
+      errors.set({ _form: 'Something went wrong. Please try again.' })
+    }
+    finally {
+      sending.set(false)
+    }
+  }
+  </script>
+
+  <div ref="host" data-form-uuid="{{ props.formUuid }}">
+    <div :if="done()" class="rounded-lg border border-green-200 bg-green-50 px-5 py-4 text-[15px] text-green-900">{{ done() }}</div>
+    <form :else-if="definition()" @submit="submit" novalidate>
+      <h2 class="text-2xl font-semibold tracking-tight">{{ definition().name }}</h2>
+      <p :if="errors()._form" class="mt-3 rounded-lg border border-red-200 bg-red-50 px-4 py-3 text-[14px] text-red-800">{{ errors()._form }}</p>
+
+      <div class="mt-6 grid grid-cols-1 gap-5 sm:grid-cols-2">
+        <template :for="field in definition().fields">
+          <div :if="fieldVisible(field)" class="{{ field.width === 'half' ? '' : 'sm:col-span-2' }}">
+            <h3 :if="field.type === 'section_break'" class="mt-2 border-t border-gray-200 pt-4 text-lg font-medium">{{ field.label }}</h3>
+            <template :else>
+              <label class="block text-[14px] font-medium text-gray-800">{{ field.label }}<span :if="field.required" aria-hidden="true" class="text-red-500"> *</span></label>
+              <textarea :if="field.type === 'textarea'" rows="4" :required="field.required" placeholder="{{ field.options.placeholder ?? '' }}" @input="values[field.name] = $event.target.value" class="mt-1.5 w-full rounded-lg border border-gray-300 px-3.5 py-2.5 text-[15px]"></textarea>
+              <select :else-if="field.type === 'select'" :required="field.required" @change="values[field.name] = $event.target.value" class="mt-1.5 w-full rounded-lg border border-gray-300 px-3.5 py-2.5 text-[15px] bg-white">
+                <option value="">Choose...</option>
+                <option :for="choice in field.options.choices ?? []" value="{{ choice.value }}">{{ choice.label }}</option>
+              </select>
+              <div :else-if="field.type === 'radio'" class="mt-2 space-y-2">
+                <label :for="choice in field.options.choices ?? []" class="flex items-center gap-2.5 text-[15px]">
+                  <input type="radio" name="{{ field.name }}" value="{{ choice.value }}" @change="values[field.name] = $event.target.value" class="h-4 w-4">
+                  {{ choice.label }}
+                </label>
+              </div>
+              <label :else-if="field.type === 'checkbox'" class="mt-2 flex items-center gap-2.5 text-[15px]">
+                <input type="checkbox" @change="values[field.name] = $event.target.checked" class="h-4 w-4 rounded">
+                {{ field.options.placeholder ?? 'Yes' }}
+              </label>
+              <input :else type="{{ field.type === 'email' ? 'email' : (field.type === 'phone' ? 'tel' : (field.type === 'date' ? 'date' : (field.type === 'currency' ? 'number' : 'text'))) }}" :required="field.required" placeholder="{{ field.options.placeholder ?? '' }}" @input="values[field.name] = field.type === 'currency' ? Math.round(Number($event.target.value) * 100) : $event.target.value" class="mt-1.5 w-full rounded-lg border border-gray-300 px-3.5 py-2.5 text-[15px]">
+              <p :if="errors()[field.name]" class="mt-1.5 text-[13px] text-red-600">{{ errors()[field.name] }}</p>
+            </template>
+          </div>
+        </template>
+      </div>
+
+      <input type="text" name="website" tabindex="-1" autocomplete="off" aria-hidden="true" class="hidden" @input="values._hp = $event.target.value">
+
+      <button type="submit" :disabled="sending()" class="mt-7 rounded-lg px-6 py-3 font-medium bg-gray-900 text-white transition-transform active:scale-[0.98] disabled:opacity-60">
+        {{ sending() ? 'Sending...' : (definition().submitLabel ?? 'Submit') }}
+      </button>
+    </form>
+    <p :else class="text-[15px] text-gray-500">Loading form...</p>
+  </div>
+</div>

package/resources/views/cms/blocks/hero.stx

@@ -0,0 +1,16 @@
+{{-- Hero block: heading, optional subheading/image/CTA. --}}
+<section class="cms-hero relative overflow-hidden {{ props.align === 'center' ? 'text-center' : 'text-left' }}">
+  @if (props.imageUrl)
+    <img src="{{ props.imageUrl }}" alt="" class="absolute inset-0 h-full w-full object-cover" aria-hidden="true">
+    <div class="absolute inset-0 bg-black/45" aria-hidden="true"></div>
+  @endif
+  <div class="relative mx-auto max-w-4xl px-6 py-24 {{ props.imageUrl ? 'text-white' : '' }}">
+    <h1 class="text-4xl md:text-6xl tracking-tighter leading-none font-semibold">{{ props.heading }}</h1>
+    @if (props.subheading)
+      <p class="mt-5 text-lg md:text-xl max-w-[65ch] {{ props.align === 'center' ? 'mx-auto' : '' }} opacity-90">{{ props.subheading }}</p>
+    @endif
+    @if (props.ctaLabel && props.ctaHref)
+      <a href="{{ props.ctaHref }}" class="mt-8 inline-block rounded-lg px-6 py-3 font-medium bg-white text-gray-900 shadow-sm transition-transform active:scale-[0.98]">{{ props.ctaLabel }}</a>
+    @endif
+  </div>
+</section>

package/resources/views/cms/blocks/image.stx

@@ -0,0 +1,7 @@
+{{-- Image block with required alt text (the editor enforces it; the schema requires it). --}}
+<figure class="cms-image mx-auto px-6 py-8 {{ props.width === 'full' ? 'max-w-none px-0' : (props.width === 'wide' ? 'max-w-6xl' : 'max-w-3xl') }}">
+  <img src="{{ props.src }}" alt="{{ props.alt }}" class="w-full rounded-lg" loading="lazy">
+  @if (props.caption)
+    <figcaption class="mt-3 text-sm text-gray-500">{{ props.caption }}</figcaption>
+  @endif
+</figure>

package/resources/views/cms/blocks/rich-text.stx

@@ -0,0 +1,4 @@
+{{-- Rich text block. `props.html` is sanitized by the render pipeline before it gets here. --}}
+<div class="cms-rich-text mx-auto max-w-3xl px-6 py-8 leading-relaxed">
+  {!! props.html !!}
+</div>

package/resources/views/cms/page.stx

@@ -0,0 +1,28 @@
+{{--
+  The default CMS page shell. Every published block-document page renders
+  through this template unless the app overrides it at
+  `resources/views/cms/page.stx`. It receives:
+
+    site    - { id, name, subdomain, settings } for the request's site
+    page    - { id, title, path, template, metaDescription }
+    content - the pre-rendered, sanitized block HTML
+
+  Deliberately minimal chrome: real sites override this to add their own
+  navigation (fetchMenuTree), theme tokens and footer.
+--}}
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{ page.title }}</title>
+  @if (page.metaDescription)
+    <meta name="description" content="{{ page.metaDescription }}">
+  @endif
+</head>
+<body>
+  <main class="cms-page" data-template="{{ page.template }}">
+    {!! content !!}
+  </main>
+</body>
+</html>

package/routes/auth.ts

@@ -34,6 +34,13 @@ import { route } from '@stacksjs/router'
 // `routes/api.ts` (user routes win) gets to pick its own limits.
 route.post('/login', 'Actions/Auth/LoginAction').rateLimit(5, 'minute')
 route.post('/register', 'Actions/Auth/RegisterAction').rateLimit(3, 'minute')
+// Magic links (config.auth.magicLink.enabled gates both, 404 when off).
+// The send endpoint answers a uniform 202 either way (anti-enumeration
+// lives in sendMagicLink); the consume endpoint is a POST because email
+// scanners prefetch GETs and would burn single-use tokens - the GET page
+// at /auth/magic/{token} is an interstitial that posts here.
+route.post('/auth/magic-link', 'Actions/Auth/MagicLinkSendAction').rateLimit(3, 'minute')
+route.post('/auth/magic-link/consume', 'Actions/Auth/MagicLinkConsumeAction').rateLimit(10, 'minute')
 // Passkey ENROLLMENT (attaching a new credential to an account) must be
 // auth-gated — it's not a login flow, it's a logged-in user adding a
 // second factor to their own account. Previously unauthenticated and

package/routes/forms.ts

@@ -0,0 +1,110 @@
+import { requestHost, resolveSiteByHost, sitesOptions } from '@stacksjs/sites'
+import { response, route } from '@stacksjs/router'
+
+/**
+ * Public form endpoints (`@stacksjs/forms`). The admin builder surface is
+ * the models' own auth'd `useApi` routes plus the export route below; these
+ * two are what a visitor's browser talks to.
+ *
+ * CSRF: the submit endpoint keeps the default-on double-submit protection.
+ * A form rendered by the CMS `form` block lives on the same origin, so the
+ * page-seeded cookie + header work exactly like every other public form.
+ * (Cross-origin embeds would need a `.skipCsrf()` variant with an Origin
+ * allowlist - deliberately not shipped until something needs it.)
+ */
+
+async function siteIdForRequest(request: any): Promise<number | null> {
+  const options = sitesOptions()
+  if (!options.enabled)
+    return null
+
+  const headers: Headers = request.headers instanceof Headers
+    ? request.headers
+    : new Headers(request.headers ?? {})
+  const site = await resolveSiteByHost(requestHost(headers, options), undefined, options)
+  return site?.id ?? null
+}
+
+route.get('/api/forms/{uuid}', async (request: any) => {
+  const { loadFormByUuid, publicDefinition } = await import('@stacksjs/forms')
+
+  const form = await loadFormByUuid(String(request.params?.uuid ?? request.param?.('uuid') ?? ''), await siteIdForRequest(request))
+  if (!form || form.status === 'draft')
+    return response.notFound('Form not found')
+
+  return response.json(publicDefinition(form))
+}).rateLimit(60, 'minute')
+
+route.post('/api/forms/{uuid}/submissions', async (request: any) => {
+  const { dispatchSubmissionNotifications, loadFormByUuid, submitForm } = await import('@stacksjs/forms')
+
+  const form = await loadFormByUuid(String(request.params?.uuid ?? request.param?.('uuid') ?? ''), await siteIdForRequest(request))
+  if (!form)
+    return response.notFound('Form not found')
+
+  const body = (typeof request.all === 'function' ? request.all() : request.body) ?? {}
+  const { _hp, _renderedMs, ...payload } = body as Record<string, unknown>
+
+  const result = await submitForm(form, payload, {
+    ip: typeof request.ip === 'function' ? request.ip() : request.ip,
+    honeypot: typeof _hp === 'string' ? _hp : undefined,
+    renderedAtMs: typeof _renderedMs === 'number' ? _renderedMs : undefined,
+  })
+
+  if (!result.ok) {
+    if (result.status === 422)
+      return response.json({ errors: result.errors }, { status: 422 })
+    return response.json({ message: result.message }, { status: result.status })
+  }
+
+  // Fire-and-forget AFTER the write: a slow mail transport must not hold a
+  // parent's phone on a spinner, and a failed one must not undo the answers.
+  if (result.submissionId > 0) {
+    void dispatchSubmissionNotifications(form, result, {
+      ...await submissionIdentity(result.submissionId),
+    }).catch(() => {})
+  }
+
+  return response.json({
+    message: result.confirmation ?? 'Thanks - your response was received.',
+    status: result.status,
+    submission: result.submissionUuid,
+    amount_cents: result.amountCents,
+    redirect: result.redirect,
+  }, { status: 201 })
+}).rateLimit(10, 'minute')
+
+async function submissionIdentity(submissionId: number): Promise<{ email: string | null, name: string | null, values: Record<string, unknown> }> {
+  const { db } = await import('@stacksjs/database')
+  const row = await db
+    .selectFrom('form_submissions')
+    .where('id', '=', submissionId)
+    .select(['email', 'name', 'values'])
+    .executeTakeFirst() as { email: string | null, name: string | null, values: string | null } | undefined
+
+  let values: Record<string, unknown> = {}
+  try {
+    values = row?.values ? JSON.parse(row.values) as Record<string, unknown> : {}
+  }
+  catch {
+    // unreadable values only degrade the notification summary
+  }
+  return { email: row?.email ?? null, name: row?.name ?? null, values }
+}
+
+/** Admin CSV export. Auth'd; site scoping rides the form lookup. */
+route.get('/api/admin/forms/{uuid}/submissions.csv', async (request: any) => {
+  const { exportSubmissionsCsv, loadFormByUuid } = await import('@stacksjs/forms')
+
+  const form = await loadFormByUuid(String(request.params?.uuid ?? request.param?.('uuid') ?? ''), await siteIdForRequest(request))
+  if (!form)
+    return response.notFound('Form not found')
+
+  const csv = await exportSubmissionsCsv(form)
+  return new Response(csv, {
+    headers: {
+      'Content-Type': 'text/csv; charset=utf-8',
+      'Content-Disposition': `attachment; filename="${form.handle}-submissions.csv"`,
+    },
+  })
+}).middleware('auth')