@commonpub/layer 0.23.2 → 0.24.0

package/components/sections/SectionLearning.vue

@@ -0,0 +1,232 @@
+<script setup lang="ts">
+/**
+ * Built-in section: learning — grid of learning paths.
+ *
+ * Fetches `/api/learn?limit=N`, renders responsive card grid (title +
+ * description + difficulty + duration + enrollment). Feature-gated
+ * upstream on `features.learning`.
+ *
+ * Same shape as editorial / content-feed (paginated /api/* endpoint →
+ * responsive grid) but a distinct entity type with its own metadata.
+ *
+ * `var(--*)` only.
+ */
+import { computed } from 'vue';
+import type { SectionRenderProps } from '@commonpub/ui';
+
+// Loose shape — full LearningPathListItem lives in @commonpub/server
+// types but the section only touches a subset. Keeping local avoids a
+// transient type import that test stubs would need to satisfy.
+interface LearningPathItem {
+  id: string;
+  slug: string;
+  title: string;
+  description: string | null;
+  coverImageUrl: string | null;
+  difficulty: string | null;
+  estimatedHours: string | null;
+  enrollmentCount: number;
+  moduleCount: number;
+}
+
+interface LearningResponse {
+  items?: LearningPathItem[];
+}
+
+interface LearningConfig extends Record<string, unknown> {
+  heading: string;
+  limit: number;
+  columns: 1 | 2 | 3 | 4;
+}
+
+const props = defineProps<SectionRenderProps<LearningConfig>>();
+
+const apiQuery = computed(() => ({
+  limit: Math.min(Math.max(props.config.limit, 1), 12),
+}));
+
+const { data: paths, pending } = useFetch<LearningResponse>(
+  '/api/learn',
+  {
+    query: apiQuery,
+    key: `section-learning:${JSON.stringify(apiQuery.value)}`,
+  },
+);
+
+const items = computed(() => paths.value?.items ?? []);
+const isEmpty = computed(() => !pending.value && items.value.length === 0);
+</script>
+
+<template>
+  <section
+    class="cpub-section-learning"
+    :aria-labelledby="config.heading ? `section-learning-${meta.sectionId}` : undefined"
+  >
+    <h2
+      v-if="config.heading"
+      :id="`section-learning-${meta.sectionId}`"
+      class="cpub-section-learning-heading"
+    >
+      {{ config.heading }}
+    </h2>
+
+    <div v-if="pending" class="cpub-section-learning-loading">
+      <i class="fa-solid fa-circle-notch fa-spin" aria-hidden="true" />
+      <span>Loading…</span>
+    </div>
+
+    <ul
+      v-else-if="!isEmpty"
+      class="cpub-section-learning-grid"
+      :data-columns="config.columns"
+    >
+      <li v-for="path in items" :key="path.id" class="cpub-section-learning-card">
+        <NuxtLink :to="`/learn/${path.slug}`" class="cpub-section-learning-link">
+          <!--
+            Using <img> rather than background-image: (a) Vue auto-escapes
+            attribute bindings so a path.coverImageUrl containing `");
+            evil(` can't escape the url(...) context (modern browsers
+            ignore JS in CSS URLs but still — defence in depth), and (b)
+            the cover IS semantically information when present, so giving
+            it an `alt` of the path title is better a11y than `role=
+            presentation`. Empty alt would also be fine here; the title
+            text directly follows.
+          -->
+          <img
+            v-if="path.coverImageUrl"
+            :src="path.coverImageUrl"
+            :alt="''"
+            loading="lazy"
+            class="cpub-section-learning-cover"
+          />
+          <div class="cpub-section-learning-body">
+            <h3 class="cpub-section-learning-title">{{ path.title }}</h3>
+            <p v-if="path.description" class="cpub-section-learning-desc">
+              {{ path.description }}
+            </p>
+            <div class="cpub-section-learning-meta">
+              <span v-if="path.difficulty" class="cpub-section-learning-chip">
+                {{ path.difficulty }}
+              </span>
+              <span v-if="path.estimatedHours" class="cpub-section-learning-chip">
+                <i class="fa-regular fa-clock" aria-hidden="true" />
+                {{ path.estimatedHours }}h
+              </span>
+              <span class="cpub-section-learning-chip">
+                {{ path.enrollmentCount }} enrolled
+              </span>
+            </div>
+          </div>
+        </NuxtLink>
+      </li>
+    </ul>
+
+    <p v-else class="cpub-section-learning-empty">No learning paths yet.</p>
+  </section>
+</template>
+
+<style scoped>
+.cpub-section-learning {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+.cpub-section-learning-heading {
+  font-family: var(--font-mono);
+  font-size: var(--text-xs);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-faint);
+  margin: 0;
+  padding-bottom: var(--space-2);
+  border-bottom: var(--border-width-default) solid var(--border);
+}
+.cpub-section-learning-grid {
+  display: grid;
+  gap: var(--space-3);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.cpub-section-learning-grid[data-columns='1'] { grid-template-columns: 1fr; }
+.cpub-section-learning-grid[data-columns='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+.cpub-section-learning-grid[data-columns='3'] { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.cpub-section-learning-grid[data-columns='4'] { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+
+@media (max-width: 1024px) {
+  .cpub-section-learning-grid[data-columns='3'],
+  .cpub-section-learning-grid[data-columns='4'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+}
+@media (max-width: 640px) {
+  .cpub-section-learning-grid { grid-template-columns: 1fr; }
+}
+
+.cpub-section-learning-card {
+  background: var(--surface);
+  border: var(--border-width-default) solid var(--border);
+  overflow: hidden;
+}
+.cpub-section-learning-link {
+  display: flex;
+  flex-direction: column;
+  color: inherit;
+  text-decoration: none;
+}
+.cpub-section-learning-cover {
+  display: block;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  object-fit: cover;
+  background-color: var(--surface-2);
+}
+.cpub-section-learning-body {
+  padding: var(--space-3);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+.cpub-section-learning-title {
+  font-size: var(--text-base);
+  font-weight: 700;
+  color: var(--text);
+  margin: 0;
+}
+.cpub-section-learning-link:hover .cpub-section-learning-title { color: var(--accent); }
+.cpub-section-learning-desc {
+  font-size: var(--text-sm);
+  color: var(--text-soft);
+  margin: 0;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+.cpub-section-learning-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+}
+.cpub-section-learning-chip {
+  font-family: var(--font-mono);
+  font-size: var(--text-xxs);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--text-faint);
+  padding: var(--space-1) var(--space-2);
+  border: var(--border-width-default) solid var(--border-soft);
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+}
+.cpub-section-learning-loading,
+.cpub-section-learning-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-2);
+  padding: var(--space-6);
+  color: var(--text-faint);
+  font-size: var(--text-sm);
+}
+</style>

package/components/sections/SectionStats.vue

@@ -0,0 +1,151 @@
+<script setup lang="ts">
+/**
+ * Built-in section: stats — a numeric grid of platform totals.
+ *
+ * Fetches `/api/stats` (returns PlatformStats), renders 2x2 grid of
+ * Projects / Posts / Members / Hubs. Hubs cell hides when the `hubs`
+ * feature flag is off — same logic as the legacy `StatsSection.vue`.
+ *
+ * Non-await useFetch per session-158 pattern; pending state surfaced
+ * via the template. SSR-friendly: useFetch includes the payload in the
+ * hydration snapshot.
+ *
+ * `var(--*)` only.
+ */
+import { computed } from 'vue';
+import type { SectionRenderProps } from '@commonpub/ui';
+
+// Avoid `import type { PlatformStats }` at the call site so the runtime
+// stub used in component tests doesn't need to satisfy the full server
+// type. Loose shape with optional + numeric primitives mirrors what the
+// endpoint actually emits.
+interface StatsResponse {
+  content?: {
+    byType?: {
+      project?: number;
+      blog?: number;
+      article?: number;
+    };
+  };
+  users?: { total?: number };
+  hubs?: { total?: number };
+}
+
+interface StatsConfig extends Record<string, unknown> {
+  heading: string;
+}
+
+const props = defineProps<SectionRenderProps<StatsConfig>>();
+
+const features = useFeatures();
+const hubsEnabled = computed(() => features.hubs.value);
+
+const { data: stats, pending } = useFetch<StatsResponse>(
+  '/api/stats',
+  {
+    key: `section-stats:${props.meta.sectionId}`,
+    // Lazy — sidebar metric tile, not above-the-fold content. Matches the
+    // legacy StatsSection.vue pattern and keeps homepage SSR fast.
+    lazy: true,
+  },
+);
+
+const projectCount = computed(() => stats.value?.content?.byType?.project ?? 0);
+const postCount = computed(
+  () => (stats.value?.content?.byType?.blog ?? 0)
+       + (stats.value?.content?.byType?.article ?? 0),
+);
+const memberCount = computed(() => stats.value?.users?.total ?? 0);
+const hubCount = computed(() => stats.value?.hubs?.total ?? 0);
+</script>
+
+<template>
+  <section
+    class="cpub-section-stats"
+    :aria-labelledby="config.heading ? `section-stats-${meta.sectionId}` : undefined"
+  >
+    <h2
+      v-if="config.heading"
+      :id="`section-stats-${meta.sectionId}`"
+      class="cpub-section-stats-heading"
+    >
+      {{ config.heading }}
+    </h2>
+
+    <div v-if="pending" class="cpub-section-stats-loading">
+      <i class="fa-solid fa-circle-notch fa-spin" aria-hidden="true" />
+    </div>
+
+    <dl v-else class="cpub-section-stats-grid" :data-with-hubs="hubsEnabled ? 'yes' : 'no'">
+      <div class="cpub-section-stats-block">
+        <dt>Projects</dt>
+        <dd>{{ projectCount }}</dd>
+      </div>
+      <div class="cpub-section-stats-block">
+        <dt>Posts</dt>
+        <dd>{{ postCount }}</dd>
+      </div>
+      <div class="cpub-section-stats-block">
+        <dt>Members</dt>
+        <dd>{{ memberCount }}</dd>
+      </div>
+      <div v-if="hubsEnabled" class="cpub-section-stats-block">
+        <dt>Hubs</dt>
+        <dd>{{ hubCount }}</dd>
+      </div>
+    </dl>
+  </section>
+</template>
+
+<style scoped>
+.cpub-section-stats {
+  background: var(--surface);
+  border: var(--border-width-default) solid var(--border);
+  padding: var(--space-4);
+}
+.cpub-section-stats-heading {
+  font-family: var(--font-mono);
+  font-size: var(--text-xxs);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-faint);
+  margin: 0 0 var(--space-3) 0;
+  padding-bottom: var(--space-2);
+  border-bottom: var(--border-width-default) solid var(--border-soft);
+}
+.cpub-section-stats-loading {
+  display: flex;
+  justify-content: center;
+  padding: var(--space-4);
+  color: var(--text-faint);
+}
+.cpub-section-stats-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: var(--space-2);
+  margin: 0;
+}
+.cpub-section-stats-block {
+  text-align: center;
+  padding: var(--space-2) 0;
+}
+.cpub-section-stats-block dt {
+  display: block;
+  font-family: var(--font-mono);
+  font-size: var(--text-xxs);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--text-faint);
+  order: 2;  /* number above label */
+}
+.cpub-section-stats-block dd {
+  display: block;
+  font-family: var(--font-mono);
+  font-size: var(--text-lg);
+  font-weight: 700;
+  color: var(--text);
+  margin: 0;
+  order: 1;
+}
+</style>

package/composables/useFeatures.ts

@@ -64,14 +64,41 @@ export const DEFAULT_FLAGS: FeatureFlags = {
   },
 };
 
-/** Build the initial flags by merging the layer's runtime config over defaults. */
+/**
+ * Build the initial flags. Two sources, in priority order:
+ *
+ *   1. **Server-side, request-scoped**: `event.context.cpubFeatureFlags` —
+ *      DB-merged values set by the Nitro `feature-flags-prime` plugin
+ *      (apps/reference/server/plugins/feature-flags-prime.ts). This is
+ *      how admin-UI flag overrides take effect at SSR time. Without it,
+ *      SSR would render with stale build-time defaults until client
+ *      hydration replaced them — visible flash + broken curl-based canary.
+ *
+ *   2. **Build-time runtime config**: `useRuntimeConfig().public.features` —
+ *      the legacy initialisation. Fallback for client-side, for early
+ *      startup before the plugin's hook can fire, and for thin apps
+ *      that haven't installed the prime plugin yet.
+ *
+ * Either way, defaults fill any unmentioned flags + identity is deep-
+ * merged so a partial override (e.g. `{ identity: { actingAs: true } }`)
+ * lands on top of the defaulted sub-flags rather than replacing the
+ * whole nested object.
+ */
 export function getInitialFlags(): FeatureFlags {
+  if (import.meta.server) {
+    // useRequestEvent is auto-imported on Nuxt server-side
+    const event = (typeof useRequestEvent === 'function') ? useRequestEvent() : null;
+    const ctxFlags = event?.context?.cpubFeatureFlags as Partial<FeatureFlags> | undefined;
+    if (ctxFlags && typeof ctxFlags === 'object') {
+      return {
+        ...DEFAULT_FLAGS,
+        ...ctxFlags,
+        identity: { ...DEFAULT_FLAGS.identity, ...(ctxFlags.identity ?? {}) },
+      };
+    }
+  }
   const config = useRuntimeConfig();
   const buildFlags = (config.public.features as unknown as Partial<FeatureFlags> | undefined) ?? {};
-  // Merge top-level booleans, but deep-merge `identity` so a partial
-  // runtime override (e.g., `{ identity: { actingAs: true } }`) lands on
-  // top of the defaulted sub-flags rather than replacing the whole
-  // nested object.
   return {
     ...DEFAULT_FLAGS,
     ...buildFlags,

package/composables/useLayout.ts

@@ -17,6 +17,7 @@
  * The `<LayoutSlot>` component is the only intended caller in v1; other
  * consumers should use that instead.
  */
+import { computed } from 'vue';
 import type { Ref } from 'vue';
 
 export interface LayoutSection {
@@ -96,6 +97,16 @@ export function useLayout(path: string | Ref<string> | (() => string)): UseLayou
         : path.value
   );
 
+  // Resolve query as a reactive computed — passing `{ path: pathGetter }`
+  // (a raw function value) made useFetch serialise the function reference,
+  // turning the request URL into ?path=undefined → 400 → null layout. The
+  // bug was load-bearing for the canary on commonpub.io (session 159): SSR
+  // saw `homepageLayout.value === null` despite a published layout existing,
+  // so layoutEngineActive resolved to false and pages/index.vue fell
+  // through to the legacy renderer. Fix: always pass a Ref/computed so
+  // useFetch reads the resolved value AND re-evaluates on dep change.
+  const queryRef = computed(() => ({ path: pathGetter() }));
+
   const { data, pending, error, refresh } = useFetch<LayoutPayload | null>(
     '/api/layouts/by-route',
     {
@@ -103,8 +114,7 @@ export function useLayout(path: string | Ref<string> | (() => string)): UseLayou
       // can dedupe across components on the same nav). For the reactive
       // case, omit key so useFetch derives one from the query Ref.
       key: typeof path === 'string' ? `layout:${path}` : undefined,
-      // Functional query — useFetch re-evaluates on watched deps change.
-      query: { path: pathGetter },
+      query: queryRef,
       // Watch the path getter so reactive callers refetch on change.
       // For string callers this is empty array → no extra reactivity.
       watch: typeof path === 'string' ? [] : [pathGetter],

package/nuxt.config.ts

@@ -82,6 +82,14 @@ export default defineNuxtConfig({
       domain: 'localhost:3000',
       siteName: 'CommonPub',
       siteDescription: 'A CommonPub instance',
+      // Nuxt only propagates env-var overrides (NUXT_PUBLIC_FEATURES_X) for
+      // keys DECLARED here. Undeclared keys are ignored at runtime, so
+      // every flag in @commonpub/config's FeatureFlags type must appear
+      // below — even if its default is false — or operators can't flip
+      // it via env var on a per-instance basis. Drift caused
+      // commonpub.io's first canary attempt to silently keep
+      // layoutEngine:false at SSR despite NUXT_PUBLIC_FEATURES_LAYOUT_ENGINE=true
+      // being set on the container.
       features: {
         content: true,
         social: true,
@@ -89,12 +97,18 @@ export default defineNuxtConfig({
         docs: true,
         video: true,
         contests: false,
+        events: false,
         learning: true,
         explainers: true,
+        editorial: true,
         federation: false,
         federateHubs: false,
+        seamlessFederation: false,
         admin: false,
         emailNotifications: false,
+        publicApi: false,
+        contentImport: true,
+        layoutEngine: false,
       },
       contentTypes: 'project,blog,explainer',
       contestCreation: 'admin',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -53,14 +53,14 @@
     "zod": "^4.3.6",
     "@commonpub/auth": "0.6.0",
     "@commonpub/config": "0.15.0",
-    "@commonpub/editor": "0.7.11",
-    "@commonpub/explainer": "0.7.15",
     "@commonpub/docs": "0.6.3",
+    "@commonpub/explainer": "0.7.15",
+    "@commonpub/server": "2.58.0",
     "@commonpub/learning": "0.5.2",
     "@commonpub/protocol": "0.12.0",
+    "@commonpub/editor": "0.7.11",
     "@commonpub/schema": "0.17.0",
-    "@commonpub/ui": "0.9.0",
-    "@commonpub/server": "2.57.0"
+    "@commonpub/ui": "0.9.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/pages/index.vue

@@ -14,9 +14,22 @@ const sortedSections = computed(() =>
 );
 
 const { user: authUser } = useAuth();
-const { hubs: hubsEnabled, contests: contestsEnabled, learning: learningEnabled, video: videoEnabled, docs: docsEnabled, editorial: editorialEnabled, layoutEngine: layoutEngineEnabled } = useFeatures();
+const { hubs: hubsEnabled, contests: contestsEnabled, learning: learningEnabled, video: videoEnabled, docs: docsEnabled, editorial: editorialEnabled, layoutEngine: layoutEngineFlag } = useFeatures();
 const { enabledTypeMeta } = useContentTypes();
 
+// Layout engine path — only active when BOTH the flag is on AND a layout
+// actually exists in the DB for this route. Prevents the "operator enables
+// the flag without seeding a homepage layout → page goes blank" trap
+// (reported by user, session 158 follow-up). When the flag's on but
+// useLayout returns null (feature off OR no published layout for route),
+// we fall through to the configurable/legacy render paths so the user
+// still sees content. Admin can call POST /api/admin/layouts/seed-homepage
+// to populate a default and start using the layout engine for real.
+const { layout: homepageLayout } = useLayout('/');
+const layoutEngineActive = computed(
+  () => layoutEngineFlag.value && homepageLayout.value !== null,
+);
+
 const activeTab = ref(authUser.value ? 'foryou' : 'latest');
 const tabs = computed(() => [
   { value: 'foryou', label: 'For You', icon: 'fa-solid fa-sparkles' },
@@ -144,15 +157,16 @@ async function handleHubJoin(hubSlug: string): Promise<void> {
 <template>
   <div>
     <!-- ═══ LAYOUT ENGINE (Phase 1c — feature-flagged) ═══
-         When `features.layoutEngine` is ON, render the homepage via
-         <LayoutSlot> zones backed by the layouts table. Operators flip
-         this on AFTER running POST /api/admin/layouts/seed-homepage so
-         a default layout exists at scope ('route', '/'). If the flag is
-         on but no layout exists, LayoutSlot renders nothing and the
-         user sees an empty page — documented at
-         docs/reference/guides/layout-engine.md. Falls through to the
-         configurable section renderer when the flag is OFF (default). -->
-    <template v-if="layoutEngineEnabled">
+         Renders DB-driven layout via <LayoutSlot> zones ONLY when BOTH
+         (a) features.layoutEngine is ON AND (b) a layout actually exists
+         at scope ('route', '/'). Falls through to the configurable or
+         legacy renderer otherwise — including when the flag's ON but
+         no layout has been seeded yet (the "blank page" trap reported
+         in session 158 follow-up).
+
+         To enable for real: POST /api/admin/layouts/seed-homepage,
+         then flip the flag. See docs/reference/guides/layout-engine.md. -->
+    <template v-if="layoutEngineActive">
       <LayoutSlot route="/" zone="full-width" />
       <div class="cpub-main-layout">
         <main class="cpub-feed-col">

package/sections/builtin/contests.ts

@@ -0,0 +1,38 @@
+/**
+ * Built-in section definition: contests.
+ *
+ * Phase 1c addition (session 159) — active-contests list. Server-fetches
+ * `/api/contests?limit=N` and renders a sidebar-style card with title,
+ * entry count, "Nd left" deadline, and per-row Enter CTA.
+ *
+ * Feature-gated on `features.contests`. If the flag is off the API
+ * returns 404; the section renders nothing (empty branch). Sidebar
+ * defaults (colSpan 4) match the legacy `ContestsSection.vue` placement.
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionContests from '../../components/sections/SectionContests.vue';
+
+const configSchema = z.object({
+  heading: z.string().max(120).default('Active Contests'),
+  limit: z.number().int().min(1).max(10).default(3),
+});
+
+export const contestsSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'contests',
+  name: 'Contests',
+  description: 'Active contests with deadlines (feature-gated)',
+  icon: 'fa-trophy',
+  category: 'data',
+  status: 'stable',
+  // Palette gate — see hubs.ts for the rationale.
+  featureGate: 'contests',
+  configSchema,
+  defaultConfig: { heading: 'Active Contests', limit: 3 },
+  schemaVersion: 1,
+  component: SectionContests,
+  minColSpan: 3,
+  maxColSpan: 12,
+  defaultColSpan: 4,
+  resizable: true,
+};

package/sections/builtin/custom-html.ts

@@ -0,0 +1,50 @@
+/**
+ * Built-in section definition: custom-html.
+ *
+ * Phase 1c addition (session 159) — admin-only raw HTML escape hatch.
+ *
+ * **SECURITY POSTURE** — important. This section renders config.html via
+ * `v-html` with NO runtime sanitization, intentionally matching the
+ * legacy `CustomHtmlSection.vue` behavior (already shipped in
+ * production for the configurable homepage path). The threat model:
+ *   - Writes are gated on `requireAdmin(event)` in
+ *     `/api/admin/layouts/*` — only trusted admin users can set HTML.
+ *   - Even so, a compromised admin account → stored XSS on every
+ *     visitor's homepage. Phase 6b will add server-side DOMPurify
+ *     sanitization at admin-write time (matching the pattern in
+ *     `packages/server/src/content/content.ts:sanitizeBlockContent`)
+ *     and an `unsafeHtmlAllowed` instance setting that gates whether
+ *     this section type can be saved at all.
+ *   - For now: `status: 'beta'` flags the risk to admin-UI consumers.
+ *     The 50KB cap is a sanity bound, not a security control.
+ *   - Tracked in docs/plans/layout-and-pages.md §6.5 (custom-html
+ *     sanitization roadmap).
+ *
+ * Use this only when no other section type fits.
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionCustomHtml from '../../components/sections/SectionCustomHtml.vue';
+
+const configSchema = z.object({
+  heading: z.string().max(120).default(''),
+  html: z.string().max(50_000).default(''),
+});
+
+export const customHtmlSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'custom-html',
+  name: 'Custom HTML',
+  description: 'Raw HTML escape hatch — admin-only; see security note in source',
+  icon: 'fa-code',
+  category: 'content',
+  // Beta marks the unsanitised render path; admin UI shows a warning chip
+  status: 'beta',
+  configSchema,
+  defaultConfig: { heading: '', html: '' },
+  schemaVersion: 1,
+  component: SectionCustomHtml,
+  minColSpan: 3,
+  maxColSpan: 12,
+  defaultColSpan: 12,
+  resizable: true,
+};