@commonpub/layer 0.83.2 → 0.85.0

package/components/contest/ContestEditor.vue

@@ -14,7 +14,6 @@
  */
 import type { Ref } from 'vue';
 import { EditorBlocks, EditorSection, useBlockEditor, BLOCK_COMPONENTS_KEY, UPLOAD_HANDLER_KEY, type BlockTypeGroup } from '@commonpub/editor/vue';
-import type { Serialized, ContestEntryItem } from '@commonpub/server';
 import type { ContestEditorSource } from '../../composables/useContestEditor';
 import JudgesShowcaseBlock from './blocks/JudgesShowcaseBlock.vue';
 import HtmlBlock from './blocks/HtmlBlock.vue';
@@ -25,6 +24,7 @@ import SponsorsBlock from './blocks/SponsorsBlock.vue';
 import CompareColumnsBlock from './blocks/CompareColumnsBlock.vue';
 import RoadmapBlock from './blocks/RoadmapBlock.vue';
 import { CONTEST_SCHEDULE_KEY, roadmapFromSchedule } from '../../utils/contestBlocks';
+import { standardContestTemplate } from '../../utils/contestTemplates';
 
 const props = defineProps<{ mode: 'create' | 'edit' }>();
 
@@ -64,12 +64,19 @@ 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, 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,
 } = editor;
 
+// Contest builder feature flags (drive the submission-form field types + the
+// new-contest template's proposal-vs-attach choice). Reactive; hydrate from
+// /api/features after mount.
+const { features } = useFeatures();
+const proposalsEnabled = computed(() => features.value.contestProposals === true);
+const piiEnabled = computed(() => features.value.contestPii === true);
+
 // --- Hoisted body block editors (the one refactor: a single left palette inserts
 // into the CURRENTLY-active body, so the three useBlockEditor instances live here
 // where the palette lives, not inside per-body components). ---
@@ -78,10 +85,15 @@ const overviewEditor = useBlockEditor(seedBodyBlocks(descriptionBlocks.value, de
 const rulesEditor = useBlockEditor(seedBodyBlocks(rulesBlocks.value, rules.value, rulesFormat.value), blockDefaults);
 const prizesEditor = useBlockEditor(seedBodyBlocks(prizesBlocks.value, prizesDescription.value, prizesDescriptionFormat.value), blockDefaults);
 
-type BodyTab = 'overview' | 'rules' | 'prizes';
+type BodyTab = 'overview' | 'rules' | 'prizes' | 'stages';
 const activeTab = ref<BodyTab>('overview');
 const bodyMode = ref<'write' | 'preview' | 'code'>('write');
-const activeBodyEditor = computed(() => ({ overview: overviewEditor, rules: rulesEditor, prizes: prizesEditor })[activeTab.value] ?? overviewEditor);
+// The Stages tab has no block editor; it falls back to overview (the palette is
+// hidden there anyway, so nothing inserts into it).
+const activeBodyEditor = computed(() => {
+  const map: Partial<Record<BodyTab, typeof overviewEditor>> = { overview: overviewEditor, rules: rulesEditor, prizes: prizesEditor };
+  return map[activeTab.value] ?? overviewEditor;
+});
 
 // Contest-specific edit block + image upload, provided once for all three bodies.
 provide(BLOCK_COMPONENTS_KEY, { judgesShowcase: JudgesShowcaseBlock, html: HtmlBlock, criteriaBar: CriteriaBarBlock, table: TableBlock, tabs: TabsBlock, sponsors: SponsorsBlock, compareColumns: CompareColumnsBlock, roadmap: RoadmapBlock });
@@ -93,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).
@@ -230,6 +256,12 @@ 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));
 
 // --- Right-rail collapsible sections ---
 const openSections = ref<Record<string, boolean>>({
@@ -240,15 +272,9 @@ function toggleSection(key: string): void {
   openSections.value[key] = !openSections.value[key];
 }
 
-// Edit-only advancement state (operates on real entries, not the editable model).
-const advancing = ref<string | null>(null);
-const advanceN = ref<Record<string, number>>({});
-const advanceMode = ref<Record<string, 'topN' | 'manual'>>({});
-const manualPick = ref<Record<string, string[]>>({});
 const deleting = ref(false);
 
-// Hydrate the form model when the contest loads (edit), and pre-fill each review
-// stage's advancement cut from its persisted advanceCount.
+// Hydrate the form model when the contest loads (edit).
 watch(contest, (c) => {
   if (!c) return;
   // Never clobber unsaved edits with a refetch (e.g. an autosave rename swaps the
@@ -256,12 +282,21 @@ watch(contest, (c) => {
   if (formDirty.value) return;
   editor.hydrate(c as ContestEditorSource);
   reseedBodies();
-  advanceN.value = {};
-  for (const s of stages.value) {
-    if (s.kind === 'review' && typeof s.advanceCount === 'number') advanceN.value[s.id] = s.advanceCount;
-  }
 }, { immediate: true });
 
+// Create mode: seed the standard starter template (a Proposals stage with a form +
+// rules agreement, a Judging stage, a Results stage, a default rubric, and starter
+// Overview/Rules copy) so a new contest doesn't start blank. Flag-adaptive: proposal
+// mode + the agreement field only seed where those builder features are on; else it
+// degrades to an attach-mode entry stage. Runs once on mount (client-only editor, so
+// the feature flags are already SSR-primed). reseedBodies() pushes the seeded body
+// blocks into the hoisted block editors.
+onMounted(() => {
+  if (props.mode !== 'create') return;
+  editor.applyTemplate(standardContestTemplate({ proposals: proposalsEnabled.value, pii: piiEnabled.value }));
+  reseedBodies();
+});
+
 async function handleDelete(): Promise<void> {
   if (!confirm('Permanently delete this contest? All entries, judges, and reviewers are removed. This cannot be undone.')) return;
   deleting.value = true;
@@ -335,55 +370,10 @@ onUnmounted(() => {
   document.removeEventListener('keydown', onStatusDocKey);
 });
 
-// Advancement cuts operate on the PERSISTED stages (contest.value), not the
-// editable `stages` ref, since they act on real entries.
+// Advancement (ContestAdvancementPanel, in the Stages tab) operates on the
+// PERSISTED review stages (contest.value), not the editable `stages` ref, since it
+// acts on real entries.
 const reviewStages = computed(() => (contest.value?.stages ?? []).filter((s) => s.kind === 'review'));
-const { data: entriesData, refresh: refreshEntries } = useLazyFetch<{ items: Serialized<ContestEntryItem>[] }>(
-  () => `/api/contests/${slug.value}/entries`,
-  { immediate: props.mode === 'edit' },
-);
-const eligibleEntries = computed(() => (entriesData.value?.items ?? []).filter((e) => !e.eliminated));
-
-function toggleManual(stageId: string, entryId: string): void {
-  const cur = manualPick.value[stageId] ?? [];
-  manualPick.value[stageId] = cur.includes(entryId) ? cur.filter((x) => x !== entryId) : [...cur, entryId];
-}
-async function advanceStageManual(stageId: string): Promise<void> {
-  const ids = manualPick.value[stageId] ?? [];
-  if (!ids.length) { toast.error('Select at least one entry to advance.'); return; }
-  if (!confirm(`Advance the ${ids.length} selected ${ids.length === 1 ? 'entry' : 'entries'}? The rest of the cohort is marked "not advanced" and drops out of later judging + final results.`)) return;
-  advancing.value = stageId;
-  try {
-    const r = await $fetch<{ advancedCount: number; eliminatedCount: number }>(`/api/contests/${slug.value}/advance`, {
-      method: 'POST',
-      body: { reviewStageId: stageId, mode: 'manual', advancedEntryIds: ids },
-    });
-    toast.success(`${r.advancedCount} advanced, ${r.eliminatedCount} not advanced.`);
-    await Promise.all([refresh(), refreshEntries()]);
-  } catch (err: unknown) {
-    toast.error(extractError(err));
-  } finally {
-    advancing.value = null;
-  }
-}
-async function advanceStage(stageId: string): Promise<void> {
-  const topN = advanceN.value[stageId];
-  if (!topN || topN < 1) { toast.error('Enter how many entries advance.'); return; }
-  if (!confirm(`Advance the top ${topN} entries from this stage? Entries below the cut are marked "not advanced" and drop out of later judging + final results. You can re-run this.`)) return;
-  advancing.value = stageId;
-  try {
-    const r = await $fetch<{ advancedCount: number; eliminatedCount: number }>(`/api/contests/${slug.value}/advance`, {
-      method: 'POST',
-      body: { reviewStageId: stageId, mode: 'topN', topN },
-    });
-    toast.success(`${r.advancedCount} advanced, ${r.eliminatedCount} not advanced.`);
-    await Promise.all([refresh(), refreshEntries()]);
-  } catch (err: unknown) {
-    toast.error(extractError(err));
-  } finally {
-    advancing.value = null;
-  }
-}
 </script>
 
 <template>
@@ -477,8 +467,9 @@ async function advanceStage(stageId: string): Promise<void> {
     </header>
 
     <div class="cpub-ce-shell">
-      <!-- LEFT: block palette — inserts into the currently-active body. -->
-      <aside class="cpub-ce-library" aria-label="Block palette">
+      <!-- LEFT: block palette — inserts into the currently-active body. Hidden on
+           the Stages tab (a form, not a block body), giving the editor more room. -->
+      <aside v-show="activeTab !== 'stages'" class="cpub-ce-library" aria-label="Block palette">
         <EditorBlocks :groups="contestBlockGroups" :block-editor="activeBodyEditor" />
       </aside>
 
@@ -496,7 +487,7 @@ async function advanceStage(stageId: string): Promise<void> {
           <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" />
+                <img v-if="bannerUrl" :src="bannerUrl" alt="Contest banner" class="cpub-ce-banner-img" :style="bannerPreviewStyle" />
                 <div v-else class="cpub-ce-media-placeholder">
                   <i class="fa-regular fa-image"></i>
                   <span>Banner image</span>
@@ -507,12 +498,13 @@ async function advanceStage(stageId: string): Promise<void> {
                     <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" />
+                  <img v-if="coverImageUrl" :src="coverImageUrl" alt="Contest cover" class="cpub-ce-cover-img" :style="coverPreviewStyle" />
                   <div v-else class="cpub-ce-media-placeholder cpub-ce-media-placeholder-sm">
                     <i class="fa-regular fa-image"></i>
                     <span>Cover</span>
@@ -522,19 +514,46 @@ async function advanceStage(stageId: string): Promise<void> {
                       <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" />
+
+              <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 zoom and reposition without re-cropping.</p>
+            </div>
+          </template>
+
+          <!-- Stages tab: the public timeline + per-stage submission forms, plus the
+               edit-only Top-N/manual advancement (which acts on real entries). -->
+          <template #stages>
+            <div class="cpub-ce-stages-tab">
+              <p class="cpub-form-hint">Stages are the public timeline (Submissions → Judging → Results, or your own rounds). Each <strong>Submissions</strong> stage carries a submission form; each <strong>Judging</strong> stage its own rubric + Top-N cut. The <strong>Status</strong> control (top bar) is what's actually open now; mark a stage <strong>Current</strong> to point judges + the countdown at it.</p>
+              <ContestStagesEditor
+                v-model="stages"
+                v-model:current-stage-id="currentStageId"
+                :start-date="startDate"
+                :end-date="endDate"
+                :judging-end-date="judgingEndDate"
+              />
+              <ContestAdvancementPanel
+                v-if="mode === 'edit' && reviewStages.length"
+                :slug="slug"
+                :review-stages="reviewStages"
+                @advanced="refresh()"
+              />
             </div>
           </template>
         </ContestBodyCanvas>
-        <p class="cpub-form-hint cpub-ce-body-hint">
+        <p v-if="activeTab !== 'stages'" class="cpub-form-hint cpub-ce-body-hint">
           The <strong>Overview</strong>, <strong>Rules</strong>, and <strong>Prizes</strong> bodies are blocks
           (headings, lists, images, callouts, and the <strong>Judges Showcase</strong>), like the project and blog
-          editors. Add blocks from the palette on the left. Stages, judging, and the rest live in the settings rail.
-          Legacy text converts to blocks on first edit.
+          editors. Add blocks from the palette on the left. The <strong>Stages</strong> tab holds the timeline +
+          submission forms; judging, prizes, and access live in the settings rail. Legacy text converts to blocks on first edit.
         </p>
       </div>
 
@@ -567,51 +586,6 @@ async function advanceStage(stageId: string): Promise<void> {
             <p v-if="dateError" class="cpub-form-error" role="alert">{{ dateError }}</p>
           </EditorSection>
 
-          <EditorSection title="Stages" icon="fa-diagram-project" :open="openSections.stages" @toggle="toggleSection('stages')">
-            <p class="cpub-form-hint">Optional. The standard flow (Submissions → Judging → Results) is derived from the schedule. Add custom stages for multi-round contests, proposal rounds, a Top-N selection, a build sprint, or a showcase event.</p>
-            <p class="cpub-form-hint">How the pieces fit: <strong>Stages</strong> are the public timeline. The <strong>Status</strong> control is what's actually open now. <strong>Advancement</strong> (below) runs each review round's Top-N cut. Mark a stage <strong>Current</strong> to point judges + the countdown at it.</p>
-            <ContestStagesEditor
-              v-model="stages"
-              v-model:current-stage-id="currentStageId"
-              :start-date="startDate"
-              :end-date="endDate"
-              :judging-end-date="judgingEndDate"
-            />
-            <div v-if="mode === 'edit' && reviewStages.length" class="cpub-advance-section">
-              <h3 class="cpub-form-subtitle">Advancement</h3>
-              <p class="cpub-form-hint">After judging a review stage, advance the top entries to the next stage. Entries below the cut are marked "not advanced". Re-running re-computes the cut. (Save any stage changes above first.)</p>
-              <div v-for="rs in reviewStages" :key="rs.id" class="cpub-advance-block">
-                <div class="cpub-advance-row">
-                  <span class="cpub-advance-name"><i class="fa-solid fa-gavel"></i> {{ rs.name }}</span>
-                  <div class="cpub-advance-mode">
-                    <label class="cpub-form-check"><input type="radio" :name="`mode-${rs.id}`" :checked="(advanceMode[rs.id] ?? 'topN') === 'topN'" @change="advanceMode[rs.id] = 'topN'" /> <span>Top N</span></label>
-                    <label class="cpub-form-check"><input type="radio" :name="`mode-${rs.id}`" :checked="advanceMode[rs.id] === 'manual'" @change="advanceMode[rs.id] = 'manual'" /> <span>Pick manually</span></label>
-                  </div>
-                </div>
-                <div v-if="(advanceMode[rs.id] ?? 'topN') === 'topN'" class="cpub-advance-ctl">
-                  <label class="cpub-form-label" :for="`adv-${rs.id}`">Advance top</label>
-                  <input :id="`adv-${rs.id}`" v-model.number="advanceN[rs.id]" type="number" min="1" class="cpub-form-input cpub-advance-n" placeholder="50" />
-                  <button type="button" class="cpub-btn cpub-btn-sm" :disabled="advancing === rs.id" @click="advanceStage(rs.id)">
-                    <i class="fa-solid fa-arrow-up-right-dots"></i> {{ advancing === rs.id ? 'Advancing…' : 'Advance' }}
-                  </button>
-                </div>
-                <div v-else class="cpub-advance-manual">
-                  <p v-if="!eligibleEntries.length" class="cpub-form-hint" style="margin: 0;">No entries in the current cohort to pick from yet.</p>
-                  <template v-else>
-                    <label v-for="e in eligibleEntries" :key="e.id" class="cpub-advance-pick">
-                      <input type="checkbox" :checked="(manualPick[rs.id] ?? []).includes(e.id)" @change="toggleManual(rs.id, e.id)" />
-                      <span class="cpub-advance-pick-title">{{ e.contentTitle }}</span>
-                      <span v-if="e.score != null" class="cpub-advance-pick-score">{{ e.score }}</span>
-                    </label>
-                    <button type="button" class="cpub-btn cpub-btn-sm" :disabled="advancing === rs.id || !(manualPick[rs.id] ?? []).length" @click="advanceStageManual(rs.id)">
-                      <i class="fa-solid fa-arrow-up-right-dots"></i> {{ advancing === rs.id ? 'Advancing…' : `Advance ${(manualPick[rs.id] ?? []).length} selected` }}
-                    </button>
-                  </template>
-                </div>
-              </div>
-            </div>
-          </EditorSection>
-
           <EditorSection title="Entries" icon="fa-inbox" :open="openSections.entries" @toggle="toggleSection('entries')">
             <div class="cpub-form-field">
               <span class="cpub-form-label">Eligible content types</span>
@@ -863,22 +837,8 @@ async function advanceStage(stageId: string): Promise<void> {
 .cpub-prize-remove { background: none; border: none; color: var(--text-faint); cursor: pointer; font-size: 12px; }
 .cpub-prize-remove:hover { color: var(--red); }
 
-/* Advancement (edit-only, inside the Stages section) */
-.cpub-advance-section { margin-top: 16px; padding-top: 12px; border-top: var(--border-width-default) solid var(--border2); }
-.cpub-advance-block { padding: 12px 0; border-top: var(--border-width-default) solid var(--border); }
-.cpub-advance-block:first-of-type { border-top: 0; }
-.cpub-advance-row { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; }
-.cpub-advance-name { font-size: 13px; font-weight: 600; display: inline-flex; align-items: center; gap: 8px; }
-.cpub-advance-name i { color: var(--accent); font-size: 11px; }
-.cpub-advance-mode { display: inline-flex; gap: 12px; }
-.cpub-advance-ctl { display: inline-flex; align-items: center; gap: 8px; margin-top: 10px; }
-.cpub-advance-ctl .cpub-form-label { margin: 0; }
-.cpub-advance-n { width: 80px; }
-.cpub-advance-manual { margin-top: 10px; display: flex; flex-direction: column; gap: 4px; }
-.cpub-advance-pick { display: flex; align-items: center; gap: 8px; font-size: 12px; color: var(--text-dim); padding: 4px 8px; border: var(--border-width-default) solid var(--border); background: var(--surface2); cursor: pointer; }
-.cpub-advance-pick-title { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.cpub-advance-pick-score { font-family: var(--font-mono); font-size: 11px; color: var(--accent); flex-shrink: 0; }
-.cpub-advance-manual .cpub-btn { align-self: flex-start; margin-top: 6px; }
+/* Stages tab (center) — the form tab gets a little breathing room. */
+.cpub-ce-stages-tab { display: flex; flex-direction: column; gap: 4px; }
 
 /* Danger zone */
 .cpub-danger-label { font-size: 13px; font-weight: 600; margin: 0 0 2px; color: var(--red); }
@@ -927,7 +887,9 @@ async function advanceStage(stageId: string): Promise<void> {
 .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-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,10 @@ 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));
+
 // 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`
@@ -142,7 +146,7 @@ const entryCount = computed<number>(() => c.value?.entryCount ?? 0);
   <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`" />
+      <img :src="c.bannerUrl" :alt="`${c?.title || 'Contest'} banner`" :style="bannerStyle" />
     </div>
 
     <!-- Compact bar — title + status + meta + actions in one tight, clean band

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

@@ -0,0 +1,207 @@
+<script setup lang="ts">
+/**
+ * ContestStageCard — one stage row in the ContestStagesEditor list, extracted so
+ * the orchestrator stays a thin list + toolbar. Presentational + intent-emitting:
+ * it renders one stage's fields and emits granular changes (`patch`, `move`,
+ * `duplicate`, `remove`, `set-current`); the parent applies them with the pure
+ * array ops in utils/contestStages.ts. Flag-gated extras (submission mode, the
+ * 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<{
+  stage: ContestStage;
+  index: number;
+  isCurrent: boolean;
+  isFirst: boolean;
+  isLast: boolean;
+}>();
+
+const emit = defineEmits<{
+  patch: [patch: Partial<ContestStage>];
+  move: [dir: -1 | 1];
+  duplicate: [];
+  remove: [];
+  'set-current': [];
+}>();
+
+const KINDS: ContestStage['kind'][] = ['submission', 'review', 'interim', 'results', 'event', 'custom'];
+
+const { features } = useFeatures();
+const templatesEnabled = computed(() => features.value.contestStageSubmissions !== false);
+const proposalsEnabled = computed(() => features.value.contestProposals === true);
+
+function setField(patch: Partial<ContestStage>): void {
+  emit('patch', patch);
+}
+function advanceCountInput(e: Event): void {
+  const v = (e.target as HTMLInputElement).value;
+  setField({ advanceCount: v === '' ? undefined : Math.max(1, Math.round(Number(v))) });
+}
+// The template editor hands back the whole field array; mirror the stored shape
+// (empty → undefined) so a cleared form drops the key entirely.
+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>
+  <li class="cpub-stage-row">
+    <div class="cpub-stage-row-head">
+      <span class="cpub-stage-num">{{ index + 1 }}</span>
+      <label class="cpub-stage-current" :title="isCurrent ? 'This is the current stage' : 'Mark as the current stage'">
+        <input
+          type="radio"
+          name="cpub-current-stage"
+          :checked="isCurrent"
+          @change="emit('set-current')"
+        />
+        <span>Current</span>
+      </label>
+      <div class="cpub-stage-row-actions">
+        <button type="button" class="cpub-stage-iconbtn" :disabled="isFirst" aria-label="Move up" @click="emit('move', -1)"><i class="fa-solid fa-arrow-up"></i></button>
+        <button type="button" class="cpub-stage-iconbtn" :disabled="isLast" aria-label="Move down" @click="emit('move', 1)"><i class="fa-solid fa-arrow-down"></i></button>
+        <button type="button" class="cpub-stage-iconbtn" aria-label="Duplicate stage" @click="emit('duplicate')"><i class="fa-solid fa-clone"></i></button>
+        <button type="button" class="cpub-stage-iconbtn cpub-stage-del" aria-label="Remove stage" @click="emit('remove')"><i class="fa-solid fa-xmark"></i></button>
+      </div>
+    </div>
+
+    <div class="cpub-form-row">
+      <div class="cpub-form-field" style="flex: 2;">
+        <label :for="`stage-name-${index}`" class="cpub-form-label">Stage name</label>
+        <input
+          :id="`stage-name-${index}`"
+          :value="stage.name"
+          type="text"
+          class="cpub-form-input"
+          placeholder="e.g. Proposals Open"
+          @input="setField({ name: ($event.target as HTMLInputElement).value })"
+        />
+      </div>
+      <div class="cpub-form-field" style="flex: 1;">
+        <label :for="`stage-type-${index}`" class="cpub-form-label">Type</label>
+        <select
+          :id="`stage-type-${index}`"
+          :value="stage.kind"
+          class="cpub-form-input"
+          @change="setField({ kind: ($event.target as HTMLSelectElement).value as ContestStage['kind'] })"
+        >
+          <option v-for="k in KINDS" :key="k" :value="k">{{ STAGE_KIND_LABEL[k] }}</option>
+        </select>
+      </div>
+    </div>
+
+    <p class="cpub-stage-kind-help"><i class="fa-solid fa-circle-info"></i> {{ STAGE_KIND_HELP[stage.kind] }}</p>
+
+    <div class="cpub-form-row">
+      <CpubDateTimeField
+        label="Starts"
+        :model-value="stage.startsAt"
+        :max="stage.endsAt"
+        @update:model-value="setField({ startsAt: $event })"
+      />
+      <CpubDateTimeField
+        label="Ends (countdown target)"
+        :model-value="stage.endsAt"
+        :min="stage.startsAt"
+        @update:model-value="setField({ endsAt: $event })"
+      />
+    </div>
+
+    <div class="cpub-form-field">
+      <label :for="`stage-desc-${index}`" class="cpub-form-label">Description (optional)</label>
+      <input
+        :id="`stage-desc-${index}`"
+        :value="stage.description ?? ''"
+        type="text"
+        class="cpub-form-input"
+        placeholder="What happens, or what to submit/refine, this stage"
+        @input="setField({ description: ($event.target as HTMLInputElement).value || undefined })"
+      />
+    </div>
+
+    <!-- Per-round config (review stages): how many advance + the rubric -->
+    <div v-if="stage.kind === 'review'" class="cpub-stage-criteria">
+      <div class="cpub-form-field" style="margin-bottom: 10px;">
+        <label :for="`stage-advance-${index}`" class="cpub-form-label">Advance the top N to the next stage</label>
+        <input :id="`stage-advance-${index}`" :value="stage.advanceCount ?? ''" type="number" min="1" class="cpub-form-input cpub-stage-advn" placeholder="e.g. 50, leave blank to decide at advance time" @input="advanceCountInput($event)" />
+      </div>
+      <p class="cpub-form-hint" style="margin: 4px 0;">Optional, leave empty to use the contest’s default criteria. Set per-round criteria for multi-round contests (e.g. judge proposals on Feasibility, prototypes on Deployment readiness).</p>
+      <ContestCriteriaEditor
+        :model-value="(stage.criteria ?? [])"
+        label="Judging criteria, this round"
+        :show-total="false"
+        @update:model-value="setField({ criteria: ($event as ContestStage['criteria']) })"
+      />
+    </div>
+
+    <!-- Submission mode (Phase 4): attach an existing project, or collect a
+         form-first proposal that seeds a draft placeholder project. -->
+    <div v-if="stage.kind === 'submission' && proposalsEnabled" class="cpub-form-field">
+      <label :for="`stage-mode-${index}`" class="cpub-form-label">How entrants submit</label>
+      <select
+        :id="`stage-mode-${index}`"
+        :value="stage.submissionMode ?? 'attach'"
+        class="cpub-form-input"
+        @change="setField({ submissionMode: (($event.target as HTMLSelectElement).value as 'attach' | 'proposal') })"
+      >
+        <option value="attach">Attach an existing published project</option>
+        <option value="proposal">Proposal form (creates a draft project)</option>
+      </select>
+      <p class="cpub-form-hint" style="margin: 4px 0;">Proposal mode lets entrants apply with just this form. The server creates a draft project they develop for later rounds.</p>
+    </div>
+
+    <!-- Per-stage submission template (submission stages): the artifact fields
+         entrants fill for THIS stage (proposal vs prototype). -->
+    <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">
+      <div class="cpub-form-field">
+        <label :for="`stage-location-${index}`" class="cpub-form-label">Location</label>
+        <input :id="`stage-location-${index}`" :value="stage.location ?? ''" type="text" class="cpub-form-input" placeholder="e.g. Washington, D.C." @input="setField({ location: ($event.target as HTMLInputElement).value || undefined })" />
+      </div>
+      <div class="cpub-form-field">
+        <label :for="`stage-url-${index}`" class="cpub-form-label">Link</label>
+        <input :id="`stage-url-${index}`" :value="stage.url ?? ''" type="url" class="cpub-form-input" placeholder="https://…" @input="setField({ url: ($event.target as HTMLInputElement).value || undefined })" />
+      </div>
+    </div>
+  </li>
+</template>
+
+<style scoped>
+/* Form controls + stage-row styles travel with this extracted markup (scoped CSS
+   doesn't cross component boundaries; the global theme only ships
+   .cpub-form-label/.cpub-form-hint/.cpub-btn). */
+.cpub-form-field { display: flex; flex-direction: column; gap: var(--space-1); margin-bottom: var(--space-3); }
+.cpub-form-field:last-child { margin-bottom: 0; }
+.cpub-form-input { width: 100%; 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); }
+.cpub-form-input:focus { border-color: var(--accent); outline: none; box-shadow: var(--shadow-accent); }
+.cpub-form-row { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: var(--space-3); }
+
+.cpub-stage-row { border: var(--border-width-default) solid var(--border); background: var(--surface2); padding: 12px; }
+.cpub-stage-row-head { display: flex; align-items: center; gap: 10px; margin-bottom: 10px; }
+.cpub-stage-num { width: 22px; height: 22px; flex-shrink: 0; display: flex; align-items: center; justify-content: center; font-size: 11px; font-weight: 700; font-family: var(--font-mono); background: var(--accent-bg); color: var(--accent); border: var(--border-width-default) solid var(--accent-border); }
+.cpub-stage-current { display: inline-flex; align-items: center; gap: 5px; font-size: 10px; font-family: var(--font-mono); text-transform: uppercase; letter-spacing: .06em; color: var(--text-faint); cursor: pointer; }
+.cpub-stage-current input { width: 13px; height: 13px; }
+.cpub-stage-row-actions { margin-left: auto; display: flex; gap: 4px; }
+.cpub-stage-iconbtn { background: var(--surface); border: var(--border-width-default) solid var(--border); color: var(--text-dim); cursor: pointer; width: 26px; height: 26px; display: inline-flex; align-items: center; justify-content: center; font-size: 11px; }
+.cpub-stage-iconbtn:hover:not(:disabled) { border-color: var(--accent); color: var(--accent); }
+.cpub-stage-iconbtn:disabled { opacity: .4; cursor: not-allowed; }
+.cpub-stage-del:hover { border-color: var(--red-border); color: var(--red); }
+.cpub-stage-kind-help { font-size: 11px; color: var(--text-faint); line-height: 1.5; margin: 0 0 4px; display: flex; gap: 6px; }
+.cpub-stage-kind-help i { color: var(--accent); margin-top: 2px; flex-shrink: 0; }
+.cpub-stage-criteria { border: var(--border-width-default) dashed var(--border2); padding: 10px; margin-top: 4px; background: var(--surface); }
+.cpub-stage-advn { max-width: 320px; }
+</style>

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); }