@commonpub/layer 0.84.0 → 0.86.0

package/components/blocks/BlockEmbedView.vue

@@ -2,10 +2,16 @@
 const props = defineProps<{ content: Record<string, unknown> }>();
 
 const embedUrl = computed(() => toEmbedUrl(props.content.url as string));
+
+type EmbedSize = 's' | 'm' | 'l' | 'full';
+const size = computed<EmbedSize>(() => {
+  const v = props.content.size;
+  return v === 's' || v === 'm' || v === 'l' || v === 'full' ? v : 'l';
+});
 </script>
 
 <template>
-  <div v-if="embedUrl" class="cpub-block-embed">
+  <div v-if="embedUrl" class="cpub-block-embed" :class="`cpub-embed-size-${size}`">
     <div class="cpub-embed-label">
       <i class="fa-solid fa-globe"></i> Embed
     </div>
@@ -17,11 +23,17 @@ const embedUrl = computed(() => toEmbedUrl(props.content.url as string));
 
 <style scoped>
 .cpub-block-embed {
-  margin: 24px 0;
+  /* width:100% so max-width caps + margin:auto centers in the flex-column renderer. */
+  width: 100%;
+  margin: 24px auto;
   border: var(--border-width-default) solid var(--border);
   overflow: hidden;
   box-shadow: var(--shadow-md);
 }
+.cpub-embed-size-s { max-width: 320px; }
+.cpub-embed-size-m { max-width: 540px; }
+.cpub-embed-size-l { max-width: 760px; }
+.cpub-embed-size-full { max-width: 100%; }
 
 .cpub-embed-label {
   padding: 6px 12px;

package/components/blocks/BlockVideoView.vue

@@ -4,6 +4,14 @@ const props = defineProps<{ content: Record<string, unknown> }>();
 const url = computed(() => (props.content.url as string) || '');
 const embedUrl = computed(() => toEmbedUrl(url.value));
 
+// Rendered-width preset (mirrors images). Missing ⇒ 'l' (760px, reading width),
+// so a video doesn't stretch full-bleed and dominate the column.
+type VideoSize = 's' | 'm' | 'l' | 'full';
+const size = computed<VideoSize>(() => {
+  const v = props.content.size;
+  return v === 's' || v === 'm' || v === 'l' || v === 'full' ? v : 'l';
+});
+
 const platform = computed(() => {
   const u = url.value;
   if (u.includes('youtube') || u.includes('youtu.be')) return 'YouTube';
@@ -13,7 +21,7 @@ const platform = computed(() => {
 </script>
 
 <template>
-  <div v-if="embedUrl" class="cpub-block-video">
+  <div v-if="embedUrl" class="cpub-block-video" :class="`cpub-video-size-${size}`">
     <div class="cpub-video-label">
       <i class="fa-solid fa-film"></i> {{ platform }}
     </div>
@@ -33,11 +41,20 @@ const platform = computed(() => {
 
 <style scoped>
 .cpub-block-video {
-  margin: 24px 0;
+  /* width:100% is required so max-width caps + margin:auto centers even inside the
+     flex-column block renderer (without it, an auto-margin flex item with no
+     intrinsic width shrinks to its label). */
+  width: 100%;
+  margin: 24px auto;
   border: var(--border-width-default) solid var(--border);
   overflow: hidden;
   box-shadow: var(--shadow-md);
 }
+/* Width presets (centered via margin:auto). Match the image-block caps. */
+.cpub-video-size-s { max-width: 320px; }
+.cpub-video-size-m { max-width: 540px; }
+.cpub-video-size-l { max-width: 760px; }
+.cpub-video-size-full { max-width: 100%; }
 
 .cpub-video-label {
   padding: 6px 12px;

package/components/contest/ContestBannerAdjust.vue

@@ -0,0 +1,157 @@
+<script setup lang="ts">
+/**
+ * ContestBannerAdjust — non-destructive framing control for a contest banner or
+ * cover (P4). Three explicit modes so the choice (and what persists) is never
+ * ambiguous:
+ *   • Fill (default)  → meta = null  → object-fit: cover (fills the band, crops).
+ *   • Fit (whole)     → meta = {zoom:0} → the WHOLE image shows (no crop). On the
+ *                        public hero the band grows to the image; here it previews
+ *                        contained.
+ *   • Zoom            → meta = {zoom>0, x, y} → cover + scale + drag-to-reposition.
+ *
+ * The earlier single slider defaulted a null banner to the "Fit" position without
+ * persisting it (moving the slider to where it already sat emitted nothing), so a
+ * banner that looked "set to Fit" stayed null → cover → cropped. Explicit mode
+ * buttons each emit a concrete value, which fixes that. Render parity with the
+ * public hero is via the shared `imageFramingStyle` / `isWholeImage`.
+ */
+import type { ContestImageMeta } from '@commonpub/schema';
+import { imageFramingStyle } from '../../utils/contestImage';
+
+defineProps<{
+  imageUrl: string;
+  /** CSS aspect-ratio for the preview box, e.g. '4 / 1' (banner), '4 / 3' (cover). */
+  aspect?: string;
+  label?: string;
+}>();
+const meta = defineModel<ContestImageMeta | null>({ default: null });
+
+const ZOOM_MIN = 0.1;
+const ZOOM_MAX = 1.5;
+const ZOOM_DEFAULT = 0.3;
+
+type Mode = 'fill' | 'fit' | 'zoom';
+const mode = computed<Mode>(() => {
+  if (!meta.value) return 'fill';
+  return meta.value.zoom <= 0 ? 'fit' : 'zoom';
+});
+const framing = computed(() => imageFramingStyle(meta.value));
+const pos = computed(() => ({ x: meta.value?.x ?? 50, y: meta.value?.y ?? 50 }));
+
+function setMode(next: Mode): void {
+  if (next === 'fill') meta.value = null;
+  else if (next === 'fit') meta.value = { zoom: 0, x: pos.value.x, y: pos.value.y };
+  else meta.value = { zoom: meta.value && meta.value.zoom > 0 ? meta.value.zoom : ZOOM_DEFAULT, x: pos.value.x, y: pos.value.y };
+}
+function onZoom(e: Event): void {
+  const zoom = Math.max(ZOOM_MIN, Number((e.target as HTMLInputElement).value));
+  meta.value = { zoom, x: pos.value.x, y: pos.value.y };
+}
+
+const MODES: { key: Mode; label: string; icon: string; hint: string }[] = [
+  { key: 'fill', label: 'Fill', icon: 'fa-expand', hint: 'Fills the banner and crops the edges.' },
+  { key: 'fit', label: 'Fit', icon: 'fa-compress', hint: 'Shows the whole image, never cropped.' },
+  { key: 'zoom', label: 'Zoom', icon: 'fa-magnifying-glass-plus', hint: 'Zoom in and drag to choose what shows.' },
+];
+const activeHint = computed(() => MODES.find((m) => m.key === mode.value)?.hint ?? '');
+
+// ─── Drag to reposition (Zoom mode only) ───
+const boxRef = ref<HTMLElement | null>(null);
+const dragging = ref(false);
+let startX = 0;
+let startY = 0;
+let startPosX = 50;
+let startPosY = 50;
+
+function onPointerDown(e: PointerEvent): void {
+  if (mode.value !== 'zoom' || !boxRef.value) return;
+  dragging.value = true;
+  startX = e.clientX;
+  startY = e.clientY;
+  startPosX = pos.value.x;
+  startPosY = pos.value.y;
+  document.addEventListener('pointermove', onPointerMove);
+  document.addEventListener('pointerup', onPointerUp);
+}
+function onPointerMove(e: PointerEvent): void {
+  if (!dragging.value || !boxRef.value || !meta.value) return;
+  const rect = boxRef.value.getBoundingClientRect();
+  const dx = ((e.clientX - startX) / Math.max(1, rect.width)) * 100;
+  const dy = ((e.clientY - startY) / Math.max(1, rect.height)) * 100;
+  meta.value = { zoom: meta.value.zoom, x: clamp(startPosX - dx), y: clamp(startPosY - dy) };
+}
+function onPointerUp(): void {
+  dragging.value = false;
+  document.removeEventListener('pointermove', onPointerMove);
+  document.removeEventListener('pointerup', onPointerUp);
+}
+function clamp(n: number): number {
+  return Math.max(0, Math.min(100, Math.round(n)));
+}
+onUnmounted(() => {
+  document.removeEventListener('pointermove', onPointerMove);
+  document.removeEventListener('pointerup', onPointerUp);
+});
+</script>
+
+<template>
+  <div class="cpub-ba">
+    <div class="cpub-ba-modes" role="group" :aria-label="`${label ?? 'Image'} framing`">
+      <button
+        v-for="m in MODES"
+        :key="m.key"
+        type="button"
+        class="cpub-ba-mode"
+        :class="{ 'cpub-ba-mode-active': mode === m.key }"
+        :aria-pressed="mode === m.key"
+        @click="setMode(m.key)"
+      >
+        <i class="fa-solid" :class="m.icon"></i> {{ m.label }}
+      </button>
+    </div>
+
+    <div
+      ref="boxRef"
+      class="cpub-ba-box"
+      :class="{ 'cpub-ba-drag': mode === 'zoom', 'cpub-ba-dragging': dragging }"
+      :style="{ aspectRatio: aspect ?? '4 / 1' }"
+      @pointerdown="onPointerDown"
+    >
+      <img :src="imageUrl" :alt="label ?? 'Image preview'" class="cpub-ba-img" :style="framing" draggable="false" />
+      <span v-if="mode === 'zoom'" class="cpub-ba-hint"><i class="fa-solid fa-up-down-left-right"></i> Drag to reposition</span>
+    </div>
+
+    <label v-if="mode === 'zoom'" class="cpub-ba-zoom">
+      <span class="cpub-ba-zoom-label">Zoom</span>
+      <input
+        type="range"
+        :min="ZOOM_MIN"
+        :max="ZOOM_MAX"
+        step="0.05"
+        :value="meta?.zoom ?? ZOOM_DEFAULT"
+        :aria-label="`${label ?? 'Image'} zoom level`"
+        @input="onZoom"
+      />
+    </label>
+
+    <p class="cpub-ba-help">{{ activeHint }}</p>
+  </div>
+</template>
+
+<style scoped>
+.cpub-ba { display: flex; flex-direction: column; gap: 8px; }
+.cpub-ba-modes { display: inline-flex; border: var(--border-width-default) solid var(--border); align-self: flex-start; }
+.cpub-ba-mode { display: inline-flex; align-items: center; gap: 5px; padding: 5px 12px; background: transparent; border: none; border-right: var(--border-width-default) solid var(--border); cursor: pointer; font-size: var(--text-xs); font-family: var(--font-mono); text-transform: uppercase; letter-spacing: .04em; color: var(--text-faint); }
+.cpub-ba-mode:last-child { border-right: none; }
+.cpub-ba-mode:hover { background: var(--surface2); color: var(--text-dim); }
+.cpub-ba-mode-active { background: var(--accent-bg); color: var(--accent); }
+.cpub-ba-box { position: relative; width: 100%; overflow: hidden; border: var(--border-width-default) solid var(--border); background: var(--surface2); touch-action: none; }
+.cpub-ba-drag { cursor: grab; }
+.cpub-ba-dragging { cursor: grabbing; }
+.cpub-ba-img { display: block; width: 100%; height: 100%; user-select: none; -webkit-user-drag: none; }
+.cpub-ba-hint { position: absolute; left: 8px; bottom: 8px; font-size: 10px; font-family: var(--font-mono); text-transform: uppercase; letter-spacing: .05em; color: var(--text); background: var(--surface); border: var(--border-width-default) solid var(--border); padding: 3px 7px; display: inline-flex; align-items: center; gap: 5px; opacity: .85; pointer-events: none; }
+.cpub-ba-zoom { display: flex; align-items: center; gap: 8px; }
+.cpub-ba-zoom-label { font-size: 11px; font-family: var(--font-mono); text-transform: uppercase; letter-spacing: .05em; color: var(--text-dim); white-space: nowrap; }
+.cpub-ba-zoom input[type='range'] { flex: 1; accent-color: var(--accent); }
+.cpub-ba-help { margin: 0; font-size: 11px; color: var(--text-faint); line-height: 1.5; }
+</style>

package/components/contest/ContestEditor.vue

@@ -64,7 +64,7 @@ const editor = useContestEditor({
 const {
   title, slugInput, slugTouched, subheading, descriptionBlocks, rulesBlocks, prizesBlocks,
   description, descriptionFormat, rules, rulesFormat, prizesDescription, prizesDescriptionFormat,
-  bannerUrl, coverImageUrl, startDate, endDate, judgingEndDate, communityVotingEnabled,
+  bannerUrl, coverImageUrl, bannerMeta, coverMeta, coverPlacement, startDate, endDate, judgingEndDate, communityVotingEnabled,
   judgingVisibility, eligibleContentTypes, maxEntriesPerUser, visibility, visibleToRoles,
   showPrizes, prizes, criteria, stages, currentStageId,
   saving, formDirty, dateError, canSubmit, slugify, toggleType, toggleRole, addPrize, removePrize, prizeLabel, save,
@@ -105,6 +105,20 @@ const scheduleRoadmap = computed(() => roadmapFromSchedule(stages.value, { start
 provide(CONTEST_SCHEDULE_KEY, scheduleRoadmap);
 const { uploadFile } = useFileUpload();
 provide(UPLOAD_HANDLER_KEY, (file: File) => uploadFile<{ url: string; width?: number | null; height?: number | null }>(file, 'content'));
+// Feed the Judges Showcase block a loader for the real scoring panel, so it can
+// offer "Import panel judges" (name + account avatar). Empty in create mode (no
+// slug yet). Maps the judges API row shape to the showcase's curated-row shape.
+provide(CONTEST_JUDGES_KEY, async () => {
+  if (!slug.value) return [];
+  const rows = await $fetch<Array<{ userName: string; userAvatar?: string | null; userUsername: string; role: string }>>(
+    `/api/contests/${slug.value}/judges`,
+  );
+  return rows.map((r) => ({
+    name: r.userName,
+    avatarUrl: r.userAvatar ?? undefined,
+    link: r.userUsername ? `/u/${r.userUsername}` : undefined,
+  }));
+});
 
 // Editor -> model write-back: each body's blocks flow into the composable's
 // descriptionBlocks/rulesBlocks/prizesBlocks refs (read by buildPayload).
@@ -242,6 +256,14 @@ function uploadMedia(event: Event, target: Ref<string>, purpose: string): void {
 function onBannerUpload(e: Event): void { uploadMedia(e, bannerUrl, 'banner'); }
 function onCoverUpload(e: Event): void { uploadMedia(e, coverImageUrl, 'cover'); }
 function onBannerUrl(): void { const url = window.prompt('Enter banner image URL:'); if (url) bannerUrl.value = url; }
+// Non-destructive framing (P4): toggle the zoom/reposition panels per image; the
+// inline previews mirror the public hero via the shared imageFramingStyle util.
+const showBannerAdjust = ref(false);
+const showCoverAdjust = ref(false);
+const bannerPreviewStyle = computed(() => imageFramingStyle(bannerMeta.value));
+const coverPreviewStyle = computed(() => imageFramingStyle(coverMeta.value));
+const bannerPreviewWhole = computed(() => isWholeImage(bannerMeta.value));
+const coverPreviewWhole = computed(() => isWholeImage(coverMeta.value));
 
 // --- Right-rail collapsible sections ---
 const openSections = ref<Record<string, boolean>>({
@@ -466,8 +488,8 @@ const reviewStages = computed(() => (contest.value?.stages ?? []).filter((s) =>
           <!-- Banner + cover render inline at the top of the Overview body only. -->
           <template #overview-lead>
             <div class="cpub-ce-media">
-              <div class="cpub-ce-banner" :class="{ 'has-image': !!bannerUrl }">
-                <img v-if="bannerUrl" :src="bannerUrl" alt="Contest banner" class="cpub-ce-banner-img" />
+              <div class="cpub-ce-banner" :class="{ 'has-image': !!bannerUrl, 'cpub-ce-banner--whole': bannerPreviewWhole }">
+                <img v-if="bannerUrl" :src="bannerUrl" alt="Contest banner" class="cpub-ce-banner-img" :style="bannerPreviewWhole ? undefined : bannerPreviewStyle" />
                 <div v-else class="cpub-ce-media-placeholder">
                   <i class="fa-regular fa-image"></i>
                   <span>Banner image</span>
@@ -478,12 +500,13 @@ const reviewStages = computed(() => (contest.value?.stages ?? []).filter((s) =>
                     <input type="file" accept="image/*" class="cpub-sr-only" aria-label="Upload banner image" @change="onBannerUpload">
                   </label>
                   <button type="button" class="cpub-ce-media-btn" @click="onBannerUrl"><i class="fa-solid fa-link"></i> URL</button>
+                  <button v-if="bannerUrl" type="button" class="cpub-ce-media-btn" :class="{ active: showBannerAdjust }" @click="showBannerAdjust = !showBannerAdjust"><i class="fa-solid fa-crop-simple"></i> Adjust</button>
                   <button v-if="bannerUrl" type="button" class="cpub-ce-media-btn" @click="bannerUrl = ''"><i class="fa-solid fa-trash"></i> Remove</button>
                 </div>
 
                 <!-- Cover thumbnail, inset over the banner's lower-left (mirrors the public hero). -->
-                <div class="cpub-ce-cover" :class="{ 'has-image': !!coverImageUrl }">
-                  <img v-if="coverImageUrl" :src="coverImageUrl" alt="Contest cover" class="cpub-ce-cover-img" />
+                <div class="cpub-ce-cover" :class="{ 'has-image': !!coverImageUrl, 'cpub-ce-cover--whole': coverPreviewWhole }">
+                  <img v-if="coverImageUrl" :src="coverImageUrl" alt="Contest cover" class="cpub-ce-cover-img" :style="coverPreviewWhole ? undefined : coverPreviewStyle" />
                   <div v-else class="cpub-ce-media-placeholder cpub-ce-media-placeholder-sm">
                     <i class="fa-regular fa-image"></i>
                     <span>Cover</span>
@@ -493,11 +516,26 @@ const reviewStages = computed(() => (contest.value?.stages ?? []).filter((s) =>
                       <i class="fa-solid fa-arrow-up-from-bracket"></i>
                       <input type="file" accept="image/*" class="cpub-sr-only" aria-label="Upload cover image" @change="onCoverUpload">
                     </label>
+                    <button v-if="coverImageUrl" type="button" class="cpub-ce-media-btn cpub-ce-media-btn-icon" :class="{ active: showCoverAdjust }" title="Adjust cover framing" @click="showCoverAdjust = !showCoverAdjust"><i class="fa-solid fa-crop-simple"></i></button>
                     <button v-if="coverImageUrl" type="button" class="cpub-ce-media-btn cpub-ce-media-btn-icon" title="Remove cover" @click="coverImageUrl = ''"><i class="fa-solid fa-trash"></i></button>
                   </div>
                 </div>
               </div>
-              <p class="cpub-form-hint cpub-ce-media-hint">Banner is the wide hero (~4:1). Cover is the card thumbnail in listings (~4:3); it falls back to the banner if unset.</p>
+
+              <!-- Non-destructive framing panels (P4) -->
+              <ContestBannerAdjust v-if="bannerUrl && showBannerAdjust" v-model="bannerMeta" :image-url="bannerUrl" aspect="4 / 1" label="Banner" class="cpub-ce-adjust" />
+              <ContestBannerAdjust v-if="coverImageUrl && showCoverAdjust" v-model="coverMeta" :image-url="coverImageUrl" aspect="4 / 3" label="Cover" class="cpub-ce-adjust" />
+
+              <!-- Where the cover image shows on the public page. -->
+              <label v-if="coverImageUrl" class="cpub-ce-cover-place">
+                <span class="cpub-form-label" style="margin: 0;">Show cover</span>
+                <select :value="coverPlacement ?? 'about'" class="cpub-form-input" @change="coverPlacement = (($event.target as HTMLSelectElement).value as 'about' | 'hero')">
+                  <option value="about">In the Overview "About" section</option>
+                  <option value="hero">In the hero, under the subheading</option>
+                </select>
+              </label>
+
+              <p class="cpub-form-hint cpub-ce-media-hint">Banner is the wide hero (~4:1). Cover is the card thumbnail in listings (~4:3); it falls back to the banner if unset. Use Adjust to set Fill, Fit (whole image), or Zoom without re-cropping.</p>
             </div>
           </template>
 
@@ -860,7 +898,15 @@ const reviewStages = computed(() => (contest.value?.stages ?? []).filter((s) =>
 .cpub-ce-media-btn:hover { background: var(--surface2); }
 .cpub-ce-media-btn.primary:hover { opacity: 0.9; background: var(--accent); }
 .cpub-ce-media-btn-icon { padding: 5px 7px; }
+.cpub-ce-media-btn.active { background: var(--accent-bg); color: var(--accent); border-color: var(--accent); }
 .cpub-ce-media-hint { margin: 0; }
+.cpub-ce-adjust { margin-top: 8px; padding: 10px; border: var(--border-width-default) solid var(--border); background: var(--surface2); }
+.cpub-ce-cover-place { display: flex; align-items: center; gap: 8px; margin-top: 8px; flex-wrap: wrap; }
+.cpub-ce-cover-place .cpub-form-input { width: auto; flex: 1; min-width: 220px; padding: var(--space-2) var(--space-3); border: var(--border-width-default) solid var(--border); background: var(--surface); color: var(--text); font-size: var(--text-sm); font-family: var(--font-sans); }
+/* Fit (whole image) previews: let the box grow to the image, no crop. */
+.cpub-ce-banner--whole { aspect-ratio: auto; max-height: 300px; }
+.cpub-ce-banner--whole .cpub-ce-banner-img { height: auto; max-height: 300px; object-fit: contain; }
+.cpub-ce-cover--whole .cpub-ce-cover-img { object-fit: contain; }
 .cpub-sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0,0,0,0); border: 0; }
 
 /* --- Responsive: stack the rail under the body on narrow viewports --- */

package/components/contest/ContestHero.vue

@@ -16,6 +16,19 @@ const emit = defineEmits<{
 
 const c = computed(() => props.contest);
 
+// Non-destructive banner framing (P4). null/absent ⇒ the legacy cover fit, so
+// existing contests look identical until an organiser adjusts framing.
+const bannerStyle = computed(() => imageFramingStyle(c.value?.bannerMeta ?? null));
+// Fit (zoom 0) shows the WHOLE banner: the band grows to the image (no crop, no
+// letterbox bars). Cover/zoom keep the slim fixed band.
+const bannerWhole = computed(() => isWholeImage(c.value?.bannerMeta ?? null));
+
+// Cover placement: `hero` renders the cover under the subheading here; otherwise it
+// stays in the Overview "About" section on the public page (default).
+const coverInHero = computed(() => c.value?.coverPlacement === 'hero' && !!c.value?.coverImageUrl);
+const coverStyle = computed(() => imageFramingStyle(c.value?.coverMeta ?? null));
+const coverWhole = computed(() => isWholeImage(c.value?.coverMeta ?? null));
+
 // Local wall-clock formatting (dates) and the live countdown are timezone- and
 // clock-dependent, so they would mismatch between the server's TZ and the viewer's
 // on hydration (and Vue won't rectify it in prod). Gate them on a client `mounted`
@@ -141,8 +154,8 @@ const entryCount = computed<number>(() => c.value?.entryCount ?? 0);
 <template>
   <div class="cpub-hero">
     <!-- Slim banner band (constrained) — the hero image, not a tall block. -->
-    <div v-if="c?.bannerUrl" class="cpub-hero-banner">
-      <img :src="c.bannerUrl" :alt="`${c?.title || 'Contest'} banner`" />
+    <div v-if="c?.bannerUrl" class="cpub-hero-banner" :class="{ 'cpub-hero-banner--whole': bannerWhole }">
+      <img :src="c.bannerUrl" :alt="`${c?.title || 'Contest'} banner`" :style="bannerWhole ? undefined : bannerStyle" />
     </div>
 
     <!-- Compact bar — title + status + meta + actions in one tight, clean band
@@ -169,6 +182,14 @@ const entryCount = computed<number>(() => c.value?.entryCount ?? 0);
 
         <h1 class="cpub-hero-title">{{ c?.title || 'Contest' }}</h1>
         <p v-if="tagline" class="cpub-hero-tagline">{{ tagline }}</p>
+        <img
+          v-if="coverInHero"
+          :src="c!.coverImageUrl!"
+          :alt="`${c?.title || 'Contest'} cover`"
+          class="cpub-hero-cover"
+          :class="{ 'cpub-hero-cover--whole': coverWhole }"
+          :style="coverWhole ? undefined : coverStyle"
+        />
 
         <div class="cpub-hero-foot">
           <div class="cpub-hero-meta">
@@ -209,6 +230,13 @@ const entryCount = computed<number>(() => c.value?.entryCount ?? 0);
   overflow: hidden;
 }
 .cpub-hero-banner img { display: block; width: 100%; height: 100%; object-fit: cover; }
+/* Fit (whole image): let the band grow to the image so nothing is cropped and there
+   are no letterbox bars (full width, natural height, capped for very tall images). */
+.cpub-hero-banner--whole { aspect-ratio: auto; max-height: none; background: transparent; }
+.cpub-hero-banner--whole img { height: auto; max-height: 70vh; object-fit: contain; }
+/* Cover image placed in the hero (under the subheading) when coverPlacement=hero. */
+.cpub-hero-cover { display: block; width: 100%; max-width: 680px; max-height: 320px; object-fit: cover; border: var(--border-width-default) solid var(--border); box-shadow: var(--shadow-md); margin: 0 0 14px; }
+.cpub-hero-cover--whole { height: auto; max-height: 420px; object-fit: contain; }
 
 /* ── COMPACT BAR ── one tight, clean band on a surface background. */
 .cpub-hero-bar { background: var(--surface); border-bottom: var(--border-width-default) solid var(--border); }
@@ -236,7 +264,7 @@ const entryCount = computed<number>(() => c.value?.entryCount ?? 0);
 .cpub-countdown-chip-muted i { color: var(--text-faint); }
 
 .cpub-hero-title { font-size: 26px; font-weight: 800; letter-spacing: -.02em; line-height: 1.15; margin: 0 0 6px; color: var(--text); }
-.cpub-hero-tagline { font-size: 13px; color: var(--text-dim); line-height: 1.55; max-width: 680px; margin: 0 0 14px; display: -webkit-box; -webkit-line-clamp: 2; line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+.cpub-hero-tagline { font-size: 14px; color: var(--text-dim); line-height: 1.6; max-width: 760px; margin: 0 0 14px; }
 
 .cpub-hero-foot { display: flex; align-items: center; justify-content: space-between; gap: 16px; flex-wrap: wrap; }
 .cpub-hero-meta { display: flex; align-items: center; gap: 18px; flex-wrap: wrap; font-size: 11px; color: var(--text-faint); font-family: var(--font-mono); }

package/components/contest/ContestProposalForm.vue

@@ -20,6 +20,7 @@ const toast = useToast();
 const { extract: extractError } = useApiError();
 
 const template = computed(() => props.stage.submissionTemplate ?? []);
+const instructions = computed(() => (props.stage.instructionsBlocks ?? []) as [string, Record<string, unknown>][]);
 const values = ref<Record<string, string>>({});
 watch(template, (t) => {
   const next: Record<string, string> = {};
@@ -59,6 +60,7 @@ async function submit(): Promise<void> {
       <h3 class="cpub-proposal-title"><i class="fa-solid fa-clipboard-list"></i> {{ stage.name }}: submit a proposal</h3>
     </div>
     <p v-if="stage.description" class="cpub-proposal-desc">{{ stage.description }}</p>
+    <BlocksBlockContentRenderer v-if="instructions.length" :blocks="instructions" class="cpub-prose cpub-md cpub-proposal-intro" />
     <p class="cpub-proposal-desc">Submitting creates a draft project you can develop for later rounds. You can edit it any time.</p>
 
     <ContestSubmissionField
@@ -84,5 +86,6 @@ async function submit(): Promise<void> {
 .cpub-proposal-title { font-size: 14px; font-weight: 700; display: flex; align-items: center; gap: 8px; margin: 0; }
 .cpub-proposal-title i { color: var(--accent); }
 .cpub-proposal-desc { font-size: 12px; color: var(--text-dim); margin: 0 0 12px; line-height: 1.6; }
+.cpub-proposal-intro { margin: 0 0 12px; }
 .cpub-proposal-actions { display: flex; align-items: center; gap: 10px; }
 </style>

package/components/contest/ContestStageCard.vue

@@ -8,6 +8,7 @@
  * submission-form builder) re-derive `useFeatures()` here rather than prop-drilling.
  */
 import type { ContestStage } from '@commonpub/schema';
+import type { BlockTuple } from '@commonpub/editor';
 import ContestStageTemplateEditor from './ContestStageTemplateEditor.vue';
 
 const props = defineProps<{
@@ -44,6 +45,10 @@ function advanceCountInput(e: Event): void {
 function onTemplateUpdate(template: ContestStage['submissionTemplate']): void {
   setField({ submissionTemplate: template && template.length ? template : undefined });
 }
+// Same for the block intro (empty → drop the key).
+function onInstructionsUpdate(blocks: BlockTuple[]): void {
+  setField({ instructionsBlocks: blocks.length ? (blocks as ContestStage['instructionsBlocks']) : undefined });
+}
 </script>
 
 <template>
@@ -157,7 +162,9 @@ function onTemplateUpdate(template: ContestStage['submissionTemplate']): void {
     <ContestStageTemplateEditor
       v-if="stage.kind === 'submission' && templatesEnabled"
       :template="stage.submissionTemplate ?? []"
+      :instructions="(stage.instructionsBlocks as BlockTuple[] | undefined)"
       @update:template="onTemplateUpdate"
+      @update:instructions="onInstructionsUpdate"
     />
 
     <div v-if="stage.kind === 'event'" class="cpub-form-row">

package/components/contest/ContestStageSubmission.vue

@@ -28,6 +28,7 @@ const toast = useToast();
 const { extract: extractError } = useApiError();
 
 const template = computed(() => props.stage.submissionTemplate ?? []);
+const instructions = computed(() => (props.stage.instructionsBlocks ?? []) as [string, Record<string, unknown>][]);
 // Eliminated entries are out of later rounds; don't offer the form for them.
 const eligibleEntries = computed(() => props.entries.filter((e) => !e.eliminated));
 const selectedEntryId = ref<string>('');
@@ -94,6 +95,7 @@ function submittedAtLabel(iso: string): string {
       </span>
     </div>
     <p v-if="stage.description" class="cpub-stagesub-desc">{{ stage.description }}</p>
+    <BlocksBlockContentRenderer v-if="instructions.length" :blocks="instructions" class="cpub-prose cpub-md cpub-stagesub-intro" />
 
     <div v-if="eligibleEntries.length > 1" class="cpub-stagesub-field">
       <label class="cpub-stagesub-label" for="cpub-stagesub-entry">Entry</label>
@@ -134,6 +136,7 @@ function submittedAtLabel(iso: string): string {
 .cpub-stagesub-done { color: var(--green); border-color: var(--green-border); background: var(--green-bg); }
 .cpub-stagesub-todo { color: var(--text-dim); border-color: var(--border2); background: var(--surface2); }
 .cpub-stagesub-desc { font-size: 12px; color: var(--text-dim); margin: 0 0 12px; line-height: 1.6; }
+.cpub-stagesub-intro { margin: 0 0 12px; }
 .cpub-stagesub-field { display: flex; flex-direction: column; gap: 4px; margin-bottom: 12px; }
 .cpub-stagesub-label { font-size: 11px; font-weight: 600; font-family: var(--font-mono); text-transform: uppercase; letter-spacing: .05em; color: var(--text-dim); }
 .cpub-stagesub-req { color: var(--red); }