@commonpub/layer 0.83.2 → 0.85.0

package/composables/useContestEditor.ts

@@ -14,7 +14,8 @@
  * round-trip bug and no per-field re-conversion at save (the Phase 1 datetime fix).
  */
 import { ref, computed, watch, nextTick, type Ref, type ComputedRef } from 'vue';
-import type { ContestStage } from '@commonpub/schema';
+import type { ContestStage, ContestImageMeta } from '@commonpub/schema';
+import type { ContestTemplateSeed } from '../utils/contestTemplates';
 
 export type ContestFormat = 'markdown' | 'html';
 export type ContestVisibility = 'public' | 'unlisted' | 'private';
@@ -51,6 +52,8 @@ export interface ContestEditorSource {
   prizesDescriptionFormat?: string | null;
   bannerUrl?: string | null;
   coverImageUrl?: string | null;
+  bannerMeta?: ContestImageMeta | null;
+  coverMeta?: ContestImageMeta | null;
   startDate?: string | null;
   endDate?: string | null;
   judgingEndDate?: string | null;
@@ -104,6 +107,8 @@ export interface UseContestEditor {
   prizesDescriptionFormat: Ref<ContestFormat>;
   bannerUrl: Ref<string>;
   coverImageUrl: Ref<string>;
+  bannerMeta: Ref<ContestImageMeta | null>;
+  coverMeta: Ref<ContestImageMeta | null>;
   startDate: Ref<string>;
   endDate: Ref<string>;
   judgingEndDate: Ref<string>;
@@ -133,6 +138,9 @@ export interface UseContestEditor {
   prizeLabel: (prize: ContestPrizeRow) => string;
   // lifecycle
   hydrate: (c: ContestEditorSource) => void;
+  /** Seed a starter template (create mode) into the stage/rubric/body refs without
+   *  marking the form dirty. Only the provided fields are applied. */
+  applyTemplate: (seed: ContestTemplateSeed) => void;
   buildPayload: () => Record<string, unknown>;
   /** Persist the form. `silent` (autosave) skips the success toast + navigation +
    *  refresh, renames in place via `onRenamed`, and rethrows on failure so the
@@ -168,6 +176,8 @@ export function useContestEditor(opts: UseContestEditorOptions): UseContestEdito
   const prizesDescriptionFormat = ref<ContestFormat>('markdown');
   const bannerUrl = ref('');
   const coverImageUrl = ref('');
+  const bannerMeta = ref<ContestImageMeta | null>(null);
+  const coverMeta = ref<ContestImageMeta | null>(null);
   const startDate = ref('');
   const endDate = ref('');
   const judgingEndDate = ref('');
@@ -248,6 +258,8 @@ export function useContestEditor(opts: UseContestEditorOptions): UseContestEdito
     prizesDescriptionFormat.value = asFormat(c.prizesDescriptionFormat);
     bannerUrl.value = c.bannerUrl ?? '';
     coverImageUrl.value = c.coverImageUrl ?? '';
+    bannerMeta.value = c.bannerMeta ?? null;
+    coverMeta.value = c.coverMeta ?? null;
     // ISO instants stored verbatim; CpubDateTimeField renders them in local time.
     startDate.value = c.startDate ?? '';
     endDate.value = c.endDate ?? '';
@@ -279,6 +291,27 @@ export function useContestEditor(opts: UseContestEditorOptions): UseContestEdito
     void nextTick(() => { hydrating = false; });
   }
 
+  // Seed a starter template into the stage/rubric/body refs (create mode). Guarded
+  // by `hydrating` so an untouched template doesn't flip `formDirty` — a freshly
+  // seeded create page should read "no unsaved changes". The orchestrator reseeds
+  // the body block editors afterward (their own `syncingBodies` guard suppresses the
+  // write-back), so seeding the body refs here is enough.
+  function applyTemplate(seed: ContestTemplateSeed): void {
+    hydrating = true;
+    stages.value = seed.stages;
+    currentStageId.value = seed.currentStageId;
+    criteria.value = seed.judgingCriteria.map((cr) => ({
+      label: cr.label,
+      weight: cr.weight ?? undefined,
+      description: cr.description ?? undefined,
+    }));
+    descriptionBlocks.value = seed.descriptionBlocks;
+    rulesBlocks.value = seed.rulesBlocks;
+    prizesBlocks.value = seed.prizesBlocks;
+    formDirty.value = false;
+    void nextTick(() => { hydrating = false; });
+  }
+
   function buildPayload(): Record<string, unknown> {
     const prizeData = prizes.value
       .filter((p) => p.title.trim() || p.description.trim() || p.category.trim() || (typeof p.place === 'number' && p.place > 0))
@@ -310,6 +343,9 @@ export function useContestEditor(opts: UseContestEditorOptions): UseContestEdito
       prizesDescriptionFormat: prizesDescriptionFormat.value,
       bannerUrl: bannerUrl.value || undefined,
       coverImageUrl: coverImageUrl.value || undefined,
+      // Clear the framing when the image is removed; else send it (or leave as-is).
+      bannerMeta: bannerUrl.value ? (bannerMeta.value ?? undefined) : null,
+      coverMeta: coverImageUrl.value ? (coverMeta.value ?? undefined) : null,
       startDate: startDate.value || undefined,
       endDate: endDate.value || undefined,
       judgingEndDate: judgingEndDate.value || undefined,
@@ -364,7 +400,7 @@ export function useContestEditor(opts: UseContestEditorOptions): UseContestEdito
   // Any post-hydration edit flips the dirty flag (drives the topbar "unsaved" cue).
   watch(
     [title, slugInput, subheading, description, descriptionBlocks, rulesBlocks, prizesBlocks, rules,
-      descriptionFormat, rulesFormat, prizesDescriptionFormat, bannerUrl, coverImageUrl, startDate, endDate,
+      descriptionFormat, rulesFormat, prizesDescriptionFormat, bannerUrl, coverImageUrl, bannerMeta, coverMeta, startDate, endDate,
       judgingEndDate, communityVotingEnabled, judgingVisibility, eligibleContentTypes, maxEntriesPerUser,
       visibility, visibleToRoles, showPrizes, prizesDescription, prizes, criteria, stages, currentStageId],
     () => { if (!hydrating) formDirty.value = true; },
@@ -378,11 +414,11 @@ export function useContestEditor(opts: UseContestEditorOptions): UseContestEdito
 
   return {
     title, slugInput, slugTouched, subheading, description, descriptionBlocks, rulesBlocks, prizesBlocks,
-    rules, descriptionFormat, rulesFormat, prizesDescriptionFormat, bannerUrl, coverImageUrl, startDate,
+    rules, descriptionFormat, rulesFormat, prizesDescriptionFormat, bannerUrl, coverImageUrl, bannerMeta, coverMeta, startDate,
     endDate, judgingEndDate, communityVotingEnabled, judgingVisibility, eligibleContentTypes, maxEntriesPerUser,
     visibility, visibleToRoles, showPrizes, prizesDescription, prizes, criteria, stages, currentStageId,
     saving, formDirty, dateError, canSubmit,
     slugify: slugifyContest, toggleType, toggleRole, addPrize, removePrize, prizeLabel,
-    hydrate, buildPayload, save,
+    hydrate, applyTemplate, buildPayload, save,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.83.2",
+  "version": "0.85.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -54,17 +54,17 @@
     "vue-advanced-cropper": "^2.8.9",
     "vue-router": "^4.3.0",
     "zod": "^4.3.6",
-    "@commonpub/auth": "0.8.0",
+    "@commonpub/config": "0.23.0",
     "@commonpub/editor": "0.8.0",
-    "@commonpub/learning": "0.5.2",
-    "@commonpub/explainer": "0.8.0",
+    "@commonpub/auth": "0.8.0",
     "@commonpub/docs": "0.6.3",
-    "@commonpub/protocol": "0.14.0",
-    "@commonpub/schema": "0.46.0",
-    "@commonpub/server": "2.90.0",
-    "@commonpub/ui": "0.13.1",
     "@commonpub/theme-studio": "0.6.1",
-    "@commonpub/config": "0.23.0"
+    "@commonpub/protocol": "0.14.0",
+    "@commonpub/schema": "0.47.0",
+    "@commonpub/learning": "0.5.2",
+    "@commonpub/server": "2.91.0",
+    "@commonpub/explainer": "0.8.0",
+    "@commonpub/ui": "0.13.1"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

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

@@ -506,7 +506,10 @@ async function withdrawEntry(entryId: string): Promise<void> {
 .cpub-submit-footer { display: flex; justify-content: flex-end; gap: 8px; padding: 12px 16px; border-top: var(--border-width-default) solid var(--border); }
 
 /* LAYOUT */
-.cpub-contest-main { max-width: 1100px; margin: 0 auto; padding: 32px; }
+/* Top padding intentionally tighter than the sides: the hero bar already sits
+   directly above with its own 20px bottom padding + border, so a full 32px here
+   stacked to a ~52px hero→tabs gap. ~18px lands the tabbar close under the hero. */
+.cpub-contest-main { max-width: 1100px; margin: 0 auto; padding: 18px 32px 32px; }
 
 .cpub-entries-tools { display: flex; justify-content: flex-end; margin-bottom: 12px; }
 .cpub-entries-cta { display: flex; align-items: center; justify-content: space-between; gap: 16px; flex-wrap: wrap; padding: 16px 20px; margin-bottom: 18px; background: var(--accent-bg); border: var(--border-width-default) solid var(--accent-border); }

package/pages/contests/index.vue

@@ -65,6 +65,7 @@ const canCreateContest = computed(() => {
             :alt="contest.title"
             class="cpub-contest-cover"
             :class="{ 'cpub-contest-cover--contain': !contest.coverImageUrl && !!contest.bannerUrl }"
+            :style="contest.coverImageUrl ? imageFramingStyle(contest.coverMeta) : undefined"
             loading="lazy"
           />
           <template v-else>

package/utils/contestBlocks.ts

@@ -19,6 +19,16 @@ export const CONTEST_RUBRIC_KEY: InjectionKey<Ref<ContestRubricCriterion[]>> = S
  *  "pull from schedule" seed. Absent (null) outside the contest editor. */
 export const CONTEST_SCHEDULE_KEY: InjectionKey<Ref<RoadmapItem[]>> = Symbol('contestSchedule');
 
+/** A panel judge as the Judges Showcase block cares about it (for "Import panel
+ *  judges": seed showcase rows from the real scoring panel). */
+export interface ContestPanelJudge { name: string; avatarUrl?: string; title?: string; link?: string }
+
+/** ContestEditor `provide`s an async loader for the contest's scoring-panel
+ *  judges under this key, so the Judges Showcase block can offer a one-click
+ *  "import panel judges" seed (name + account avatar). Resolves to [] in create
+ *  mode (no slug yet); absent (null) outside the contest editor. */
+export const CONTEST_JUDGES_KEY: InjectionKey<() => Promise<ContestPanelJudge[]>> = Symbol('contestJudges');
+
 /** A stage as the roadmap cares about it (structural subset of ContestStage). */
 export interface RoadmapStageSource { name: string; kind?: string; startsAt?: string; endsAt?: string; description?: string }
 /** The three core schedule dates, when there are no custom stages. */

package/utils/contestBody.ts

@@ -15,11 +15,11 @@ export function seedBodyBlocks(
   if (Array.isArray(blocks) && blocks.length) return blocks as BlockTuple[];
   const text = (legacy ?? '').trim();
   if (!text) return [];
-  if (legacyFormat === 'html') return [['markdown', { content: text }]];
+  if (legacyFormat === 'html') return [['markdown', { source: text }]];
   try {
     const parsed = markdownToBlockTuples(text);
-    return parsed.length ? parsed : [['markdown', { content: text }]];
+    return parsed.length ? parsed : [['markdown', { source: text }]];
   } catch {
-    return [['markdown', { content: text }]];
+    return [['markdown', { source: text }]];
   }
 }

package/utils/contestImage.ts

@@ -0,0 +1,35 @@
+import type { CSSProperties } from 'vue';
+import type { ContestImageMeta } from '@commonpub/schema';
+
+/**
+ * Map a contest banner/cover `ContestImageMeta` to CSS for the <img> (P4). The
+ * framing is NON-DESTRUCTIVE — the original upload is never re-cropped; this only
+ * drives object-fit / transform / object-position. Shared by ContestHero (public
+ * render), the editor preview, and ContestBannerAdjust so all three agree.
+ *
+ *  - `null`/absent ⇒ `cover` with NO transform — the legacy fit, so existing
+ *    contests look identical until an organiser touches the framing (back-compat).
+ *  - `zoom <= 0`   ⇒ `contain` — perfect fit, the whole image visible (letterboxed).
+ *  - `zoom > 0`    ⇒ `cover` + `scale(1 + zoom)` + `object-position: x% y%`.
+ */
+/** A `:style` object (a Vue CSSProperties subset) for an <img>. */
+export type ImageFraming = CSSProperties;
+
+export function imageFramingStyle(meta: ContestImageMeta | null | undefined): CSSProperties {
+  if (!meta) return { objectFit: 'cover' };
+  const x = clampPct(meta.x);
+  const y = clampPct(meta.y);
+  if (meta.zoom <= 0) return { objectFit: 'contain', objectPosition: `${x}% ${y}%` };
+  const zoom = Math.min(4, meta.zoom);
+  return { objectFit: 'cover', transform: `scale(${1 + zoom})`, objectPosition: `${x}% ${y}%` };
+}
+
+function clampPct(n: number): number {
+  if (!Number.isFinite(n)) return 50;
+  return Math.max(0, Math.min(100, Math.round(n)));
+}
+
+/** The default framing an organiser starts from when they first adjust an image. */
+export function defaultImageMeta(): ContestImageMeta {
+  return { zoom: 0, x: 50, y: 50 };
+}

package/utils/contestStages.ts

@@ -109,23 +109,20 @@ export function blankTemplateField(): ContestSubmissionTemplateField {
   return { key: '', label: '', type: 'text', required: false };
 }
 
-function withTemplate(stages: ContestStage[], i: number, template: ContestSubmissionTemplateField[]): ContestStage[] {
-  return stages.map((s, idx) => (idx === i ? { ...s, submissionTemplate: template.length ? template : undefined } : s));
-}
+type FieldType = ContestSubmissionTemplateField['type'];
+type TemplateField = ContestSubmissionTemplateField;
 
-export function withTemplateFieldAdded(stages: ContestStage[], i: number): ContestStage[] {
-  const cur = stages[i]?.submissionTemplate ?? [];
-  return withTemplate(stages, i, [...cur, blankTemplateField()]);
+// ─── Array-level template ops (operate on ONE stage's submissionTemplate) ───
+// The extracted ContestStageTemplateEditor works on a plain field array; the
+// stage-indexed `withTemplate*` wrappers below delegate to these so both surfaces
+// share one implementation (and the existing unit tests still exercise it).
+
+export function templateFieldAdded(t: TemplateField[]): TemplateField[] {
+  return [...t, blankTemplateField()];
 }
 
-export function withTemplateFieldSet(
-  stages: ContestStage[],
-  i: number,
-  fi: number,
-  patch: Partial<ContestSubmissionTemplateField>,
-): ContestStage[] {
-  const cur = (stages[i]?.submissionTemplate ?? []).map((f, idx) => (idx === fi ? { ...f, ...patch } : f));
-  return withTemplate(stages, i, cur);
+export function templateFieldSet(t: TemplateField[], fi: number, patch: Partial<TemplateField>): TemplateField[] {
+  return t.map((f, idx) => (idx === fi ? { ...f, ...patch } : f));
 }
 
 /**
@@ -134,28 +131,17 @@ export function withTemplateFieldSet(
  * organizer edited by hand is left alone — once entrants have submitted, keys
  * are what artifact values hang off, so they must stay stable.
  */
-export function withTemplateFieldLabelChanged(
-  stages: ContestStage[],
-  i: number,
-  fi: number,
-  label: string,
-): ContestStage[] {
-  const field = stages[i]?.submissionTemplate?.[fi];
-  if (!field) return stages;
+export function templateFieldLabelChanged(t: TemplateField[], fi: number, label: string): TemplateField[] {
+  const field = t[fi];
+  if (!field) return t;
   const tracksLabel = !field.key || field.key === fieldKeyFromLabel(field.label);
-  const patch: Partial<ContestSubmissionTemplateField> = tracksLabel
-    ? { label, key: fieldKeyFromLabel(label) }
-    : { label };
-  return withTemplateFieldSet(stages, i, fi, patch);
+  return templateFieldSet(t, fi, tracksLabel ? { label, key: fieldKeyFromLabel(label) } : { label });
 }
 
-export function withTemplateFieldRemoved(stages: ContestStage[], i: number, fi: number): ContestStage[] {
-  const cur = (stages[i]?.submissionTemplate ?? []).filter((_, idx) => idx !== fi);
-  return withTemplate(stages, i, cur);
+export function templateFieldRemoved(t: TemplateField[], fi: number): TemplateField[] {
+  return t.filter((_, idx) => idx !== fi);
 }
 
-type FieldType = ContestSubmissionTemplateField['type'];
-
 /**
  * Change a template field's type AND normalize the type-specific ancillary props
  * so the stored field stays coherent (Phase 4): `address` forces `pii`; leaving
@@ -163,15 +149,10 @@ type FieldType = ContestSubmissionTemplateField['type'];
  * `mustAccept`; entering `select` seeds one blank option; entering `agreement`
  * defaults `mustAccept` true.
  */
-export function withTemplateFieldTypeChanged(
-  stages: ContestStage[],
-  i: number,
-  fi: number,
-  type: FieldType,
-): ContestStage[] {
-  const field = stages[i]?.submissionTemplate?.[fi];
-  if (!field) return stages;
-  const patch: Partial<ContestSubmissionTemplateField> = { type };
+export function templateFieldTypeChanged(t: TemplateField[], fi: number, type: FieldType): TemplateField[] {
+  const field = t[fi];
+  if (!field) return t;
+  const patch: Partial<TemplateField> = { type };
   patch.options = type === 'select' ? (field.options?.length ? field.options : [{ value: '', label: '' }]) : undefined;
   if (type === 'agreement') {
     patch.mustAccept = field.mustAccept ?? true;
@@ -181,13 +162,64 @@ export function withTemplateFieldTypeChanged(
     patch.mustAccept = undefined;
   }
   if (type === 'address') patch.pii = true;
-  return withTemplateFieldSet(stages, i, fi, patch);
+  return templateFieldSet(t, fi, patch);
+}
+
+export function templateOptionAdded(t: TemplateField[], fi: number): TemplateField[] {
+  const field = t[fi];
+  if (!field) return t;
+  return templateFieldSet(t, fi, { options: [...(field.options ?? []), { value: '', label: '' }] });
+}
+
+export function templateOptionSet(
+  t: TemplateField[],
+  fi: number,
+  oi: number,
+  patch: Partial<{ value: string; label: string }>,
+): TemplateField[] {
+  const field = t[fi];
+  if (!field) return t;
+  const options = (field.options ?? []).map((o, idx) => (idx === oi ? { ...o, ...patch } : o));
+  return templateFieldSet(t, fi, { options });
+}
+
+export function templateOptionRemoved(t: TemplateField[], fi: number, oi: number): TemplateField[] {
+  const field = t[fi];
+  if (!field) return t;
+  return templateFieldSet(t, fi, { options: (field.options ?? []).filter((_, idx) => idx !== oi) });
+}
+
+// ─── Stage-indexed wrappers (delegate to the array-level ops above) ───
+
+function withTemplate(stages: ContestStage[], i: number, template: TemplateField[]): ContestStage[] {
+  return stages.map((s, idx) => (idx === i ? { ...s, submissionTemplate: template.length ? template : undefined } : s));
+}
+
+export function withTemplateFieldAdded(stages: ContestStage[], i: number): ContestStage[] {
+  return withTemplate(stages, i, templateFieldAdded(stages[i]?.submissionTemplate ?? []));
+}
+
+export function withTemplateFieldSet(stages: ContestStage[], i: number, fi: number, patch: Partial<TemplateField>): ContestStage[] {
+  return withTemplate(stages, i, templateFieldSet(stages[i]?.submissionTemplate ?? [], fi, patch));
+}
+
+export function withTemplateFieldLabelChanged(stages: ContestStage[], i: number, fi: number, label: string): ContestStage[] {
+  if (!stages[i]?.submissionTemplate?.[fi]) return stages;
+  return withTemplate(stages, i, templateFieldLabelChanged(stages[i]!.submissionTemplate!, fi, label));
+}
+
+export function withTemplateFieldRemoved(stages: ContestStage[], i: number, fi: number): ContestStage[] {
+  return withTemplate(stages, i, templateFieldRemoved(stages[i]?.submissionTemplate ?? [], fi));
+}
+
+export function withTemplateFieldTypeChanged(stages: ContestStage[], i: number, fi: number, type: FieldType): ContestStage[] {
+  if (!stages[i]?.submissionTemplate?.[fi]) return stages;
+  return withTemplate(stages, i, templateFieldTypeChanged(stages[i]!.submissionTemplate!, fi, type));
 }
 
 export function withTemplateOptionAdded(stages: ContestStage[], i: number, fi: number): ContestStage[] {
-  const field = stages[i]?.submissionTemplate?.[fi];
-  if (!field) return stages;
-  return withTemplateFieldSet(stages, i, fi, { options: [...(field.options ?? []), { value: '', label: '' }] });
+  if (!stages[i]?.submissionTemplate?.[fi]) return stages;
+  return withTemplate(stages, i, templateOptionAdded(stages[i]!.submissionTemplate!, fi));
 }
 
 export function withTemplateOptionSet(
@@ -197,16 +229,13 @@ export function withTemplateOptionSet(
   oi: number,
   patch: Partial<{ value: string; label: string }>,
 ): ContestStage[] {
-  const field = stages[i]?.submissionTemplate?.[fi];
-  if (!field) return stages;
-  const options = (field.options ?? []).map((o, idx) => (idx === oi ? { ...o, ...patch } : o));
-  return withTemplateFieldSet(stages, i, fi, { options });
+  if (!stages[i]?.submissionTemplate?.[fi]) return stages;
+  return withTemplate(stages, i, templateOptionSet(stages[i]!.submissionTemplate!, fi, oi, patch));
 }
 
 export function withTemplateOptionRemoved(stages: ContestStage[], i: number, fi: number, oi: number): ContestStage[] {
-  const field = stages[i]?.submissionTemplate?.[fi];
-  if (!field) return stages;
-  return withTemplateFieldSet(stages, i, fi, { options: (field.options ?? []).filter((_, idx) => idx !== oi) });
+  if (!stages[i]?.submissionTemplate?.[fi]) return stages;
+  return withTemplate(stages, i, templateOptionRemoved(stages[i]!.submissionTemplate!, fi, oi));
 }
 
 /** Human label for each template field type (for the editor dropdown). */

package/utils/contestSubmissionTemplates.ts

@@ -0,0 +1,165 @@
+import type { ContestSubmissionTemplateField } from '@commonpub/schema';
+import { fieldKeyFromLabel } from './contestStages';
+
+/**
+ * Field presets + whole-form templates for the submission-form builder (P2). Pure
+ * data + helpers so they unit-test in isolation; the builder UI
+ * (ContestStageTemplateEditor) appends a preset or replaces the whole form via the
+ * `templatePreset*`/template builders here. Keys are derived from the label and
+ * uniquified against the existing template so two "Email" fields don't collide
+ * (template field keys must be unique — `contestStageSchema`).
+ *
+ * Address/Agreement presets + the address/shipping templates are PII-gated
+ * (`features.contestPii`): the agreement/address field types are only offered in
+ * the builder when that flag is on, so the UI hides them otherwise. The pure
+ * builders take an explicit `{ pii }` so they degrade the same way in isolation.
+ */
+type TemplateField = ContestSubmissionTemplateField;
+
+/** Default terms an organiser can keep or edit; shared by the preset + template. */
+export const RULES_AGREEMENT_TERMS =
+  'By entering, I confirm this submission is my own original work and I agree to the contest rules and code of conduct.';
+
+/** Make `base` unique within `taken` by appending `_2`, `_3`, … */
+function uniqueKey(taken: Set<string>, base: string): string {
+  if (!taken.has(base)) return base;
+  let n = 2;
+  while (taken.has(`${base}_${n}`)) n += 1;
+  return `${base}_${n}`;
+}
+
+/** Stamp keys on a set of keyless fields, keeping them unique among themselves. */
+function withKeys(fields: Array<Omit<TemplateField, 'key'> & { key?: string }>): TemplateField[] {
+  const taken = new Set<string>();
+  return fields.map((f) => {
+    const key = uniqueKey(taken, f.key || fieldKeyFromLabel(f.label));
+    taken.add(key);
+    return { ...f, key };
+  });
+}
+
+// ─── One-click field presets (the "Add field" menu) ───
+
+export interface FieldPreset {
+  id: string;
+  /** Menu label. */
+  label: string;
+  /** FontAwesome icon (no `fa-solid` prefix). */
+  icon: string;
+  /** Requires `features.contestPii` (agreement/address field types). */
+  pii?: boolean;
+  /** The field this preset seeds (key derived from the label at add time). */
+  field: Omit<TemplateField, 'key'>;
+}
+
+export const FIELD_PRESETS: FieldPreset[] = [
+  { id: 'text', label: 'Short text', icon: 'fa-font', field: { label: 'Short answer', type: 'text', required: false } },
+  { id: 'textarea', label: 'Long text', icon: 'fa-align-left', field: { label: 'Details', type: 'textarea', required: false } },
+  { id: 'url', label: 'Link (URL)', icon: 'fa-link', field: { label: 'Link', type: 'url', required: false, help: 'Include the full https:// address.' } },
+  { id: 'email', label: 'Email', icon: 'fa-envelope', field: { label: 'Email address', type: 'email', required: false } },
+  { id: 'number', label: 'Number', icon: 'fa-hashtag', field: { label: 'Number', type: 'number', required: false } },
+  { id: 'select', label: 'Dropdown', icon: 'fa-list', field: { label: 'Choose one', type: 'select', required: false, options: [{ value: '', label: '' }] } },
+  { id: 'checkbox', label: 'Checkbox', icon: 'fa-square-check', field: { label: 'Confirm', type: 'checkbox', required: false } },
+  { id: 'date', label: 'Date', icon: 'fa-calendar', field: { label: 'Date', type: 'date', required: false } },
+  {
+    id: 'address',
+    label: 'Mailing address',
+    icon: 'fa-location-dot',
+    pii: true,
+    field: { label: 'Mailing address', type: 'address', required: false, pii: true, help: 'Stored privately. Only staff with PII access and the entrant can read it.' },
+  },
+  {
+    id: 'agreement',
+    label: 'Agreement',
+    icon: 'fa-file-signature',
+    pii: true,
+    field: { label: 'Agreement', type: 'agreement', required: true, mustAccept: true, terms: RULES_AGREEMENT_TERMS },
+  },
+];
+
+/** Presets offered for the builder, gated by whether PII field types are enabled. */
+export function availableFieldPresets(pii: boolean): FieldPreset[] {
+  return pii ? FIELD_PRESETS : FIELD_PRESETS.filter((p) => !p.pii);
+}
+
+/** Append a preset field, deriving a unique machine key from its label. */
+export function templatePresetAdded(t: TemplateField[], preset: FieldPreset): TemplateField[] {
+  const taken = new Set(t.map((f) => f.key));
+  const key = uniqueKey(taken, fieldKeyFromLabel(preset.field.label));
+  return [...t, { ...preset.field, key }];
+}
+
+// ─── Whole-form templates (the "Start from template" picker) ───
+
+export interface SubmissionFormTemplate {
+  id: string;
+  label: string;
+  description: string;
+  /** Requires `features.contestPii` to seed its address/agreement fields. */
+  pii?: boolean;
+  /** Build the field array; flag-adaptive so it degrades when PII is off. */
+  build(opts: { pii: boolean }): TemplateField[];
+}
+
+const SHIPPING_AGREEMENT_TERMS =
+  'If selected, I agree to provide a valid shipping address and accept responsibility for any hardware sent to me.';
+
+export const SUBMISSION_FORM_TEMPLATES: SubmissionFormTemplate[] = [
+  {
+    id: 'standard',
+    label: 'Standard proposal',
+    description: 'Name, summary, description, approach (and a rules agreement when PII is on).',
+    build({ pii }): TemplateField[] {
+      const fields: Array<Omit<TemplateField, 'key'>> = [
+        { label: 'Project name', type: 'text', required: true },
+        { label: 'One-line summary', type: 'text', required: true, help: 'A single sentence describing your idea.' },
+        { label: 'Description', type: 'textarea', required: true, help: 'What you are building and the problem it solves.' },
+        { label: 'Approach', type: 'textarea', required: false, help: 'How you plan to build it (optional).' },
+      ];
+      if (pii) fields.push({ label: 'Contest rules', type: 'agreement', required: true, terms: RULES_AGREEMENT_TERMS, mustAccept: true });
+      return withKeys(fields);
+    },
+  },
+  {
+    id: 'hardware',
+    label: 'Hardware / shipping',
+    description: 'Standard proposal plus a mailing address and a shipping agreement (PII).',
+    pii: true,
+    build({ pii }): TemplateField[] {
+      const fields: Array<Omit<TemplateField, 'key'>> = [
+        { label: 'Project name', type: 'text', required: true },
+        { label: 'One-line summary', type: 'text', required: true, help: 'A single sentence describing your idea.' },
+        { label: 'Description', type: 'textarea', required: true, help: 'What you are building and the problem it solves.' },
+      ];
+      if (pii) {
+        fields.push({ label: 'Mailing address', type: 'address', required: true, pii: true, help: 'Stored privately. Only staff with PII access and the entrant can read it.' });
+        fields.push({ label: 'Shipping agreement', type: 'agreement', required: true, terms: SHIPPING_AGREEMENT_TERMS, mustAccept: true });
+      }
+      return withKeys(fields);
+    },
+  },
+  {
+    id: 'minimal',
+    label: 'Minimal',
+    description: 'Just a project name and a link.',
+    build(): TemplateField[] {
+      return withKeys([
+        { label: 'Project name', type: 'text', required: true },
+        { label: 'Link', type: 'url', required: false, help: 'Include the full https:// address.' },
+      ]);
+    },
+  },
+  {
+    id: 'blank',
+    label: 'Blank',
+    description: 'Start with no fields.',
+    build(): TemplateField[] {
+      return [];
+    },
+  },
+];
+
+/** Templates offered for the builder, gated by whether PII field types are enabled. */
+export function availableFormTemplates(pii: boolean): SubmissionFormTemplate[] {
+  return pii ? SUBMISSION_FORM_TEMPLATES : SUBMISSION_FORM_TEMPLATES.filter((t) => !t.pii);
+}