@commonpub/layer 0.51.0 → 0.52.0

package/components/contest/ContestHero.vue

@@ -84,31 +84,10 @@ const dateNote = computed<string | null>(() => {
   return c.value?.endDate ? `Closed ${fmtDate(c.value.endDate)}` : null;
 });
 
-// Client-side mirror of the server VALID_TRANSITIONS map (server/src/contest/contest.ts).
-// Keeps the inline admin controls in sync with what the API will actually accept —
-// bidirectional: go back a stage, pause/resume, reopen, etc.
-const VALID_TRANSITIONS: Record<string, string[]> = {
-  draft: ['upcoming', 'active', 'cancelled'],
-  upcoming: ['draft', 'active', 'cancelled'],
-  active: ['upcoming', 'paused', 'judging', 'cancelled'],
-  paused: ['active', 'upcoming', 'judging', 'cancelled'],
-  judging: ['active', 'paused', 'completed', 'cancelled'],
-  completed: ['judging'],
-  cancelled: ['draft', 'upcoming'],
-};
-const STATUS_ACTION: Record<string, { label: string; icon: string }> = {
-  draft: { label: 'Move to Draft', icon: 'fa-pen-ruler' },
-  upcoming: { label: 'Set Upcoming', icon: 'fa-clock' },
-  active: { label: 'Activate', icon: 'fa-play' },
-  paused: { label: 'Pause', icon: 'fa-pause' },
-  judging: { label: 'Start Judging', icon: 'fa-gavel' },
-  completed: { label: 'Complete', icon: 'fa-check' },
-  cancelled: { label: 'Cancel', icon: 'fa-ban' },
-};
-const availableTransitions = computed<string[]>(() => VALID_TRANSITIONS[c.value?.status ?? 'upcoming'] ?? []);
-function statusAction(s: string): { label: string; icon: string } {
-  return STATUS_ACTION[s] ?? { label: s, icon: 'fa-circle' };
-}
+// Bidirectional lifecycle controls — the valid-transition map + button metadata
+// live in utils/contestTransitions.ts (shared with the contest edit page).
+const availableTransitions = computed<string[]>(() => contestTransitionsFrom(c.value?.status));
+const statusAction = contestStatusAction;
 
 // The hero shows the short `subheading` (a dedicated tagline field). For older
 // contests without one, fall back to a clean, plain-text, CSS-clamped excerpt of
@@ -120,6 +99,15 @@ const tagline = computed<string>(() => {
   return markdownToExcerpt(c.value?.description) || '';
 });
 
+// Phase B1 — when a contest defines explicit stages, surface the current stage's
+// name beside the status pill (default-flow contests show nothing extra).
+const currentStageName = computed<string | null>(() => {
+  const cv = c.value;
+  if (!cv || !cv.stages || cv.stages.length === 0) return null;
+  const cid = currentStageId(cv);
+  return cv.stages.find((s) => s.id === cid)?.name ?? null;
+});
+
 const dateRange = computed<string>(() => {
   const fmt = (d: string, withYear = false) =>
     new Date(d).toLocaleDateString('en-US', { month: 'short', day: 'numeric', ...(withYear ? { year: 'numeric' } : {}) });
@@ -157,6 +145,7 @@ const dateRange = computed<string>(() => {
             <div class="cpub-hero-eyebrow">
               <span class="cpub-contest-badge"><i class="fa fa-trophy"></i> Contest</span>
               <span class="cpub-status-pill" :data-status="c?.status || 'upcoming'">{{ c?.status || 'upcoming' }}</span>
+              <span v-if="currentStageName" class="cpub-stage-chip"><i class="fa-solid fa-diagram-project"></i> {{ currentStageName }}</span>
             </div>
 
             <h1 class="cpub-hero-title">{{ c?.title || 'Contest' }}</h1>
@@ -290,6 +279,8 @@ const dateRange = computed<string>(() => {
 .cpub-status-pill[data-status="paused"] { color: var(--yellow); border-color: var(--yellow); background: color-mix(in srgb, var(--yellow) 12%, transparent); }
 .cpub-status-pill[data-status="draft"] { color: var(--hero-text-dim); border-color: var(--hero-border); border-style: dashed; }
 .cpub-status-pill[data-status="completed"], .cpub-status-pill[data-status="cancelled"] { color: var(--red); border-color: var(--red-border); }
+.cpub-stage-chip { font-size: 9px; font-weight: 700; letter-spacing: .1em; text-transform: uppercase; font-family: var(--font-mono); padding: 3px 10px; border-radius: var(--radius); border: var(--border-width-default) solid var(--accent); color: var(--accent); background: var(--accent-bg); display: inline-flex; align-items: center; gap: 5px; }
+.cpub-stage-chip i { font-size: 8px; }
 
 .cpub-hero-title { font-size: 34px; font-weight: 800; letter-spacing: -.03em; line-height: 1.1; margin: 0 0 10px; color: var(--hero-text); }
 .cpub-hero-tagline { font-size: 14px; color: var(--hero-text-dim); line-height: 1.55; max-width: 600px; margin: 0 0 20px; display: -webkit-box; -webkit-line-clamp: 4; line-clamp: 4; -webkit-box-orient: vertical; overflow: hidden; }

package/components/contest/ContestSidebar.vue

@@ -20,24 +20,21 @@ function fmt(d: string | null | undefined): string | null {
   return new Date(d).toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
 }
 
-// Ordinal position of each status along the lifecycle, used to mark steps
-// done / current / upcoming.
-// `draft` precedes everything (nothing has started); `paused` sits at the active
-// position (a deactivated-but-not-cancelled running contest).
-const STATUS_ORDER: Record<string, number> = { draft: -1, upcoming: 0, active: 1, paused: 1, judging: 2, completed: 3 };
-
+// Phase B1 — the timeline renders the contest's stages (its explicit `stages`, or
+// the synthesized classic Submissions → Judging → Results when none are defined).
+// done/current/upcoming derive from the position of the current stage.
 const timeline = computed<TimelineStep[]>(() => {
   const c = props.contest;
   if (!c || c.status === 'cancelled') return [];
-  const pos = STATUS_ORDER[c.status] ?? 0;
-  const stepState = (idx: number): StepState => (idx < pos ? 'done' : idx === pos ? 'current' : 'upcoming');
-  const steps: TimelineStep[] = [
-    { label: 'Opens', date: fmt(c.startDate), state: stepState(0), icon: 'fa-flag' },
-    { label: 'Submissions close', date: fmt(c.endDate), state: stepState(1), icon: 'fa-pen-to-square' },
-    { label: 'Judging', date: fmt(c.judgingEndDate) ?? fmt(c.endDate), state: stepState(2), icon: 'fa-gavel' },
-    { label: 'Results', date: null, state: stepState(3), icon: 'fa-ranking-star' },
-  ];
-  return steps;
+  const stages = normalizeStages(c);
+  const curId = currentStageId(c);
+  const curIdx = curId ? stages.findIndex((s) => s.id === curId) : -1;
+  return stages.map((s, i): TimelineStep => ({
+    label: s.name,
+    date: fmt(s.endsAt ?? s.startsAt ?? null),
+    state: curIdx < 0 ? 'upcoming' : i < curIdx ? 'done' : i === curIdx ? 'current' : 'upcoming',
+    icon: STAGE_KIND_ICON[s.kind] ?? 'fa-circle-dot',
+  }));
 });
 
 function statusClass(status: string): string {

package/components/contest/ContestStagesEditor.vue

@@ -0,0 +1,217 @@
+<script setup lang="ts">
+import type { ContestStage } from '@commonpub/schema';
+
+// Phase B1 — define an arbitrary, ordered stage timeline for a contest. Empty ⇒
+// the contest uses the synthesized standard flow (Submissions → Judging → Results),
+// so this editor is opt-in. `kind` drives display + how the stage maps to the coarse
+// status; `name`/dates are arbitrary. Used by both create.vue and edit.vue.
+
+const stages = defineModel<ContestStage[]>({ required: true });
+// Local name `currentId` avoids colliding with the auto-imported `currentStageId`
+// util (the model name string stays `currentStageId` for the parent v-model).
+const currentId = defineModel<string | null>('currentStageId', { default: null });
+
+const props = defineProps<{
+  // Contest dates — used to seed the synthesized stages when the owner customizes.
+  startDate: string;
+  endDate: string;
+  judgingEndDate?: string | null;
+}>();
+
+const KINDS: ContestStage['kind'][] = ['submission', 'review', 'interim', 'results', 'event', 'custom'];
+
+function newId(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  return c?.randomUUID?.() ?? `s-${Date.now()}-${Math.round(Math.random() * 1e6)}`;
+}
+
+// datetime-local <-> ISO (mirrors the rest of the contest forms' convention).
+function toLocal(iso?: string): string {
+  if (!iso) return '';
+  try { return new Date(iso).toISOString().slice(0, 16); } catch { return ''; }
+}
+function toIso(local: string): string | undefined {
+  if (!local) return undefined;
+  const d = new Date(local);
+  return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+}
+
+function commit(next: ContestStage[]): void {
+  stages.value = next;
+}
+
+function setField(i: number, patch: Partial<ContestStage>): void {
+  const next = stages.value.map((s, idx) => (idx === i ? { ...s, ...patch } : s));
+  commit(next);
+}
+
+function onDate(i: number, field: 'startsAt' | 'endsAt', e: Event): void {
+  const v = toIso((e.target as HTMLInputElement).value);
+  setField(i, { [field]: v } as Partial<ContestStage>);
+}
+
+function addStage(): void {
+  commit([...stages.value, { id: newId(), name: '', kind: 'custom' }]);
+}
+
+function duplicateStage(i: number): void {
+  const src = stages.value[i];
+  if (!src) return;
+  const copy: ContestStage = { ...src, id: newId(), name: `${src.name} (copy)`, core: false };
+  commit([...stages.value.slice(0, i + 1), copy, ...stages.value.slice(i + 1)]);
+}
+
+function removeStage(i: number): void {
+  const removed = stages.value[i];
+  commit(stages.value.filter((_, idx) => idx !== i));
+  if (removed && currentId.value === removed.id) currentId.value = null;
+}
+
+function move(i: number, dir: -1 | 1): void {
+  const j = i + dir;
+  if (j < 0 || j >= stages.value.length) return;
+  const next = [...stages.value];
+  [next[i], next[j]] = [next[j]!, next[i]!];
+  commit(next);
+}
+
+// Seed the editor with the standard three stages so the owner has a starting point.
+function customize(): void {
+  const iso = (d?: string | null) => (d ? new Date(d).toISOString() : undefined);
+  commit([
+    { id: newId(), name: 'Submissions', kind: 'submission', startsAt: iso(props.startDate), endsAt: iso(props.endDate) },
+    { id: newId(), name: 'Judging', kind: 'review', endsAt: iso(props.judgingEndDate) ?? iso(props.endDate) },
+    { id: newId(), name: 'Results', kind: 'results' },
+  ]);
+}
+
+function resetToStandard(): void {
+  currentId.value = null;
+  commit([]);
+}
+
+const missingSubmission = computed(() => stages.value.length > 0 && !stages.value.some((s) => s.kind === 'submission'));
+</script>
+
+<template>
+  <div class="cpub-stages-editor">
+    <!-- Empty state: standard flow -->
+    <div v-if="!stages.length" class="cpub-stages-standard">
+      <p class="cpub-form-hint" style="margin: 0;">
+        This contest uses the <strong>standard flow</strong>: Submissions → Judging → Results, driven by
+        the schedule dates above. Customize only if you need extra rounds (e.g. a proposal round, a
+        Top-N selection, a build sprint, multiple judging rounds, or a showcase event).
+      </p>
+      <button type="button" class="cpub-btn cpub-btn-sm" @click="customize">
+        <i class="fa-solid fa-diagram-project"></i> Customize stages
+      </button>
+    </div>
+
+    <template v-else>
+      <p v-if="missingSubmission" class="cpub-form-error" role="alert" style="margin: 0 0 10px;">
+        Add at least one <strong>Submissions</strong> stage, or reset to the standard flow.
+      </p>
+
+      <ol class="cpub-stage-list">
+        <li v-for="(stage, i) in stages" :key="stage.id" class="cpub-stage-row">
+          <div class="cpub-stage-row-head">
+            <span class="cpub-stage-num">{{ i + 1 }}</span>
+            <label class="cpub-stage-current" :title="currentId === stage.id ? 'This is the current stage' : 'Mark as the current stage'">
+              <input
+                type="radio"
+                name="cpub-current-stage"
+                :checked="currentId === stage.id"
+                @change="currentId = stage.id"
+              />
+              <span>Current</span>
+            </label>
+            <div class="cpub-stage-row-actions">
+              <button type="button" class="cpub-stage-iconbtn" :disabled="i === 0" aria-label="Move up" @click="move(i, -1)"><i class="fa-solid fa-arrow-up"></i></button>
+              <button type="button" class="cpub-stage-iconbtn" :disabled="i === stages.length - 1" aria-label="Move down" @click="move(i, 1)"><i class="fa-solid fa-arrow-down"></i></button>
+              <button type="button" class="cpub-stage-iconbtn" aria-label="Duplicate stage" @click="duplicateStage(i)"><i class="fa-solid fa-clone"></i></button>
+              <button type="button" class="cpub-stage-iconbtn cpub-stage-del" aria-label="Remove stage" @click="removeStage(i)"><i class="fa-solid fa-xmark"></i></button>
+            </div>
+          </div>
+
+          <div class="cpub-form-row">
+            <div class="cpub-form-field" style="flex: 2;">
+              <label class="cpub-form-label">Stage name</label>
+              <input
+                :value="stage.name"
+                type="text"
+                class="cpub-form-input"
+                placeholder="e.g. Proposals Open"
+                @input="setField(i, { name: ($event.target as HTMLInputElement).value })"
+              />
+            </div>
+            <div class="cpub-form-field" style="flex: 1;">
+              <label class="cpub-form-label">Type</label>
+              <select
+                :value="stage.kind"
+                class="cpub-form-input"
+                @change="setField(i, { 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>
+
+          <div class="cpub-form-row">
+            <div class="cpub-form-field">
+              <label class="cpub-form-label">Starts</label>
+              <input type="datetime-local" class="cpub-form-input" :value="toLocal(stage.startsAt)" @input="onDate(i, 'startsAt', $event)" />
+            </div>
+            <div class="cpub-form-field">
+              <label class="cpub-form-label">Ends (countdown target)</label>
+              <input type="datetime-local" class="cpub-form-input" :value="toLocal(stage.endsAt)" @input="onDate(i, 'endsAt', $event)" />
+            </div>
+          </div>
+
+          <div class="cpub-form-field">
+            <label class="cpub-form-label">Description (optional)</label>
+            <input
+              :value="stage.description ?? ''"
+              type="text"
+              class="cpub-form-input"
+              placeholder="What happens — or what to submit/refine — this stage"
+              @input="setField(i, { description: ($event.target as HTMLInputElement).value || undefined })"
+            />
+          </div>
+
+          <div v-if="stage.kind === 'event'" class="cpub-form-row">
+            <div class="cpub-form-field">
+              <label class="cpub-form-label">Location</label>
+              <input :value="stage.location ?? ''" type="text" class="cpub-form-input" placeholder="e.g. Washington, D.C." @input="setField(i, { location: ($event.target as HTMLInputElement).value || undefined })" />
+            </div>
+            <div class="cpub-form-field">
+              <label class="cpub-form-label">Link</label>
+              <input :value="stage.url ?? ''" type="url" class="cpub-form-input" placeholder="https://…" @input="setField(i, { url: ($event.target as HTMLInputElement).value || undefined })" />
+            </div>
+          </div>
+        </li>
+      </ol>
+
+      <div class="cpub-stage-toolbar">
+        <button type="button" class="cpub-btn cpub-btn-sm" @click="addStage"><i class="fa-solid fa-plus"></i> Add stage</button>
+        <button type="button" class="cpub-btn cpub-btn-sm cpub-stage-reset" @click="resetToStandard"><i class="fa-solid fa-rotate-left"></i> Reset to standard flow</button>
+      </div>
+    </template>
+  </div>
+</template>
+
+<style scoped>
+.cpub-stages-standard { display: flex; flex-direction: column; gap: 10px; align-items: flex-start; }
+.cpub-stage-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 10px; }
+.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-toolbar { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 12px; }
+.cpub-stage-reset { color: var(--text-faint); }
+</style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -53,16 +53,16 @@
     "vue": "^3.4.0",
     "vue-router": "^4.3.0",
     "zod": "^4.3.6",
+    "@commonpub/editor": "0.7.11",
     "@commonpub/auth": "0.8.0",
     "@commonpub/config": "0.18.0",
     "@commonpub/docs": "0.6.3",
-    "@commonpub/explainer": "0.7.15",
-    "@commonpub/editor": "0.7.11",
-    "@commonpub/learning": "0.5.2",
-    "@commonpub/schema": "0.28.0",
     "@commonpub/protocol": "0.13.0",
+    "@commonpub/schema": "0.29.0",
+    "@commonpub/server": "2.76.0",
     "@commonpub/ui": "0.9.2",
-    "@commonpub/server": "2.75.0"
+    "@commonpub/learning": "0.5.2",
+    "@commonpub/explainer": "0.7.15"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/pages/contests/[slug]/edit.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import type { ContestStage } from '@commonpub/schema';
+
 definePageMeta({ middleware: 'auth' });
 
 const route = useRoute();
@@ -55,6 +57,10 @@ const prizes = ref<Prize[]>([]);
 interface Criterion { label: string; weight: number | null; description: string }
 const criteria = ref<Criterion[]>([]);
 
+// Phase B1 — explicit stage timeline (empty ⇒ standard synthesized flow).
+const stages = ref<ContestStage[]>([]);
+const currentStageIdRef = ref<string | null>(null);
+
 // Load current data
 watch(contest, (c) => {
   if (!c) return;
@@ -75,6 +81,8 @@ watch(contest, (c) => {
   visibility.value = (c.visibility as typeof visibility.value) ?? 'public';
   visibleToRoles.value = [...(c.visibleToRoles ?? [])];
   showPrizes.value = c.showPrizes !== false;
+  stages.value = Array.isArray(c.stages) ? [...c.stages] : [];
+  currentStageIdRef.value = c.currentStageId ?? null;
   prizesDescription.value = c.prizesDescription ?? '';
   prizes.value = (c.prizes ?? []).map((p: { place?: number; category?: string; title?: string; description?: string; value?: string }) => ({
     place: p.place ?? null,
@@ -166,6 +174,8 @@ async function handleSave(): Promise<void> {
         visibility: visibility.value,
         visibleToRoles: visibility.value === 'private' ? visibleToRoles.value : [],
         showPrizes: showPrizes.value,
+        stages: stages.value,
+        currentStageId: currentStageIdRef.value ?? undefined,
         prizesDescription: prizesDescription.value || undefined,
         prizes: prizeData,
         judgingCriteria: criteriaData,
@@ -201,30 +211,10 @@ async function handleDelete(): Promise<void> {
   }
 }
 
-// Client mirror of the server VALID_TRANSITIONS map — bidirectional (go back a
-// stage, pause/resume, reopen). Kept in sync with server/src/contest/contest.ts.
-const VALID_TRANSITIONS: Record<string, string[]> = {
-  draft: ['upcoming', 'active', 'cancelled'],
-  upcoming: ['draft', 'active', 'cancelled'],
-  active: ['upcoming', 'paused', 'judging', 'cancelled'],
-  paused: ['active', 'upcoming', 'judging', 'cancelled'],
-  judging: ['active', 'paused', 'completed', 'cancelled'],
-  completed: ['judging'],
-  cancelled: ['draft', 'upcoming'],
-};
-const STATUS_ACTION: Record<string, { label: string; icon: string; tone?: 'go' | 'warn' | 'danger' }> = {
-  draft: { label: 'Move to Draft', icon: 'fa-pen-ruler' },
-  upcoming: { label: 'Set Upcoming', icon: 'fa-clock' },
-  active: { label: 'Activate', icon: 'fa-play', tone: 'go' },
-  paused: { label: 'Pause', icon: 'fa-pause', tone: 'warn' },
-  judging: { label: 'Begin Judging', icon: 'fa-gavel' },
-  completed: { label: 'Complete & Publish', icon: 'fa-flag-checkered', tone: 'go' },
-  cancelled: { label: 'Cancel', icon: 'fa-ban', tone: 'danger' },
-};
-const availableTransitions = computed<string[]>(() => VALID_TRANSITIONS[contest.value?.status ?? 'upcoming'] ?? []);
-function statusAction(s: string): { label: string; icon: string; tone?: string } {
-  return STATUS_ACTION[s] ?? { label: s, icon: 'fa-circle' };
-}
+// Bidirectional lifecycle controls — the valid-transition map + button metadata
+// live in utils/contestTransitions.ts (shared with ContestHero).
+const availableTransitions = computed<string[]>(() => contestTransitionsFrom(contest.value?.status));
+const statusAction = contestStatusAction;
 
 async function transitionStatus(newStatus: string): Promise<void> {
   // Only the consequential transitions confirm; reversible nudges (pause/resume,
@@ -307,6 +297,18 @@ async function transitionStatus(newStatus: string): Promise<void> {
         <p v-if="dateError" class="cpub-form-error" role="alert">{{ dateError }}</p>
       </section>
 
+      <section class="cpub-form-section">
+        <h2 class="cpub-form-section-title">Stages</h2>
+        <p class="cpub-form-hint">Optional. The standard flow (Submissions → Judging → Results) is derived from the schedule above. Add custom stages for multi-round contests — proposal rounds, a Top-N selection, a build sprint, multiple judging rounds, or a showcase event.</p>
+        <ContestStagesEditor
+          v-model="stages"
+          v-model:current-stage-id="currentStageIdRef"
+          :start-date="startDate"
+          :end-date="endDate"
+          :judging-end-date="judgingEndDate"
+        />
+      </section>
+
       <section class="cpub-form-section">
         <h2 class="cpub-form-section-title">Entries</h2>
         <div class="cpub-form-field">

package/pages/contests/create.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import type { ContestStage } from '@commonpub/schema';
+
 definePageMeta({ middleware: 'auth' });
 
 useSeoMeta({ title: `Create Contest — ${useSiteName()}` });
@@ -57,6 +59,10 @@ interface Prize {
 
 const showPrizes = ref(true);
 const prizesDescription = ref('');
+
+// Phase B1 — explicit stage timeline (empty ⇒ standard synthesized flow).
+const stages = ref<ContestStage[]>([]);
+const currentStageIdRef = ref<string | null>(null);
 // Prizes are entirely optional — start empty so a contest has NO prizes unless
 // the operator explicitly adds them (the old 3 pre-filled rows forced prizes
 // onto every contest, since their non-empty titles survived the submit filter).
@@ -116,6 +122,8 @@ async function handleCreate(): Promise<void> {
         eligibleContentTypes: eligibleContentTypes.value.length ? eligibleContentTypes.value : undefined,
         maxEntriesPerUser: maxEntriesPerUser.value && maxEntriesPerUser.value > 0 ? maxEntriesPerUser.value : undefined,
         showPrizes: showPrizes.value,
+        stages: stages.value.length ? stages.value : undefined,
+        currentStageId: currentStageIdRef.value ?? undefined,
         prizesDescription: prizesDescription.value || undefined,
         prizes: prizes.value
           .filter(p => p.title.trim() || p.description.trim() || p.category.trim() || (typeof p.place === 'number' && p.place > 0))
@@ -215,6 +223,19 @@ function prizeLabel(prize: Prize): string {
         <p v-if="dateError" class="cpub-form-error" role="alert">{{ dateError }}</p>
       </section>
 
+      <!-- Stages -->
+      <section class="cpub-form-section">
+        <h2 class="cpub-form-section-title">Stages <span style="color: var(--text-faint); font-weight: 400; font-size: 0.75em; font-family: var(--font-mono);">— optional</span></h2>
+        <p class="cpub-form-hint">The standard flow (Submissions → Judging → Results) is derived from the schedule above. Add custom stages for multi-round contests — proposal rounds, a Top-N selection, a build sprint, multiple judging rounds, or a showcase event.</p>
+        <ContestStagesEditor
+          v-model="stages"
+          v-model:current-stage-id="currentStageIdRef"
+          :start-date="startDate"
+          :end-date="endDate"
+          :judging-end-date="judgingEndDate"
+        />
+      </section>
+
       <!-- Visibility & Access -->
       <section class="cpub-form-section">
         <h2 class="cpub-form-section-title">Visibility &amp; Access</h2>

package/utils/contestStages.ts

@@ -0,0 +1,70 @@
+import type { ContestStage } from '@commonpub/schema';
+
+// Client mirror of the pure stage helpers in @commonpub/server `contest.ts`
+// (synthesizeStages / normalizeStages / currentStage). Deliberately duplicated —
+// importing the server package into the browser bundle would pull in DB drivers.
+// If the server derivation changes, change this in lockstep (same contract as the
+// VALID_TRANSITIONS mirror in ContestHero/edit.vue).
+
+export interface StageSource {
+  status: string;
+  startDate: string;
+  endDate: string;
+  judgingEndDate: string | null;
+  stages?: ContestStage[] | null;
+  currentStageId?: string | null;
+}
+
+const iso = (d: string | null | undefined): string | undefined => (d ? new Date(d).toISOString() : undefined);
+
+/** Classic Submissions → Judging → Results, synthesized from status + dates. */
+export function synthesizeStages(c: StageSource): ContestStage[] {
+  return [
+    { id: 'core-submission', name: 'Submissions', kind: 'submission', core: true, startsAt: iso(c.startDate), endsAt: iso(c.endDate) },
+    { id: 'core-review', name: 'Judging', kind: 'review', core: true, endsAt: iso(c.judgingEndDate) ?? iso(c.endDate) },
+    { id: 'core-results', name: 'Results', kind: 'results', core: true },
+  ];
+}
+
+/** Explicit stages if defined, else the synthesized classic flow (the default). */
+export function normalizeStages(c: StageSource): ContestStage[] {
+  return c.stages && c.stages.length > 0 ? c.stages : synthesizeStages(c);
+}
+
+/** Id of the stage that is "now" — the resolvable `currentStageId`, else derived
+ *  from `status`. Null while draft/cancelled (nothing running). */
+export function currentStageId(c: StageSource): string | null {
+  const stages = normalizeStages(c);
+  if (c.currentStageId && stages.some((s) => s.id === c.currentStageId)) return c.currentStageId;
+  switch (c.status) {
+    case 'draft':
+    case 'cancelled':
+      return null;
+    case 'completed':
+      return (stages.find((s) => s.kind === 'results') ?? stages[stages.length - 1])?.id ?? null;
+    case 'judging':
+      return stages.find((s) => s.kind === 'review')?.id ?? null;
+    default: // upcoming | active | paused
+      return (stages.find((s) => s.kind === 'submission') ?? stages[0])?.id ?? null;
+  }
+}
+
+/** FontAwesome icon (no `fa-solid` prefix) for each stage kind. */
+export const STAGE_KIND_ICON: Record<ContestStage['kind'], string> = {
+  submission: 'fa-pen-to-square',
+  review: 'fa-gavel',
+  interim: 'fa-screwdriver-wrench',
+  results: 'fa-ranking-star',
+  event: 'fa-flag-checkered',
+  custom: 'fa-circle-dot',
+};
+
+/** Human label for each stage kind (for the editor dropdown). */
+export const STAGE_KIND_LABEL: Record<ContestStage['kind'], string> = {
+  submission: 'Submissions',
+  review: 'Judging / Review',
+  interim: 'Working period (sprint)',
+  results: 'Results',
+  event: 'Event / Showcase',
+  custom: 'Custom milestone',
+};

package/utils/contestTransitions.ts

@@ -0,0 +1,34 @@
+// Client mirror of the server VALID_TRANSITIONS map (@commonpub/server contest.ts).
+// Single source of truth for the contest lifecycle controls in ContestHero and
+// the contest edit page — keeps the offered buttons in sync with what the API
+// accepts. If the server map changes, change this in lockstep (a client-only or
+// server-only edit silently desyncs: the UI offers a button the API rejects).
+
+export const CONTEST_VALID_TRANSITIONS: Record<string, string[]> = {
+  draft: ['upcoming', 'active', 'cancelled'],
+  upcoming: ['draft', 'active', 'cancelled'],
+  active: ['upcoming', 'paused', 'judging', 'cancelled'],
+  paused: ['active', 'upcoming', 'judging', 'cancelled'],
+  judging: ['active', 'paused', 'completed', 'cancelled'],
+  completed: ['judging'],
+  cancelled: ['draft', 'upcoming'],
+};
+
+/** Display metadata for a transition target. `tone` styles the button (go/warn/danger). */
+export const CONTEST_STATUS_ACTION: Record<string, { label: string; icon: string; tone?: 'go' | 'warn' | 'danger' }> = {
+  draft: { label: 'Move to Draft', icon: 'fa-pen-ruler' },
+  upcoming: { label: 'Set Upcoming', icon: 'fa-clock' },
+  active: { label: 'Activate', icon: 'fa-play', tone: 'go' },
+  paused: { label: 'Pause', icon: 'fa-pause', tone: 'warn' },
+  judging: { label: 'Start Judging', icon: 'fa-gavel' },
+  completed: { label: 'Complete & Publish', icon: 'fa-flag-checkered', tone: 'go' },
+  cancelled: { label: 'Cancel', icon: 'fa-ban', tone: 'danger' },
+};
+
+export function contestTransitionsFrom(status: string | undefined): string[] {
+  return CONTEST_VALID_TRANSITIONS[status ?? 'upcoming'] ?? [];
+}
+
+export function contestStatusAction(s: string): { label: string; icon: string; tone?: string } {
+  return CONTEST_STATUS_ACTION[s] ?? { label: s, icon: 'fa-circle' };
+}