@commonpub/layer 0.82.0 → 0.83.1

package/server/plugins/federation-hub-sync.ts

@@ -9,7 +9,7 @@ import {
   fetchRemoteHubFollowers,
 } from '@commonpub/server';
 import { federatedHubs } from '@commonpub/schema';
-import { eq, and, or, lt, isNull } from 'drizzle-orm';
+import { eq, and, or, lt, isNull, inArray } from 'drizzle-orm';
 
 const MAX_HUBS_PER_CYCLE = 5;
 const STAGGER_DELAY_MS = 2_000;
@@ -56,28 +56,57 @@ export default defineNitroPlugin((nitro) => {
       const now = new Date();
       const staleThreshold = new Date(now.getTime() - intervalMs);
 
-      // Find accepted, non-hidden hubs where lastSyncAt is older than the interval or null
-      const staleHubs = await db
-        .select({
-          id: federatedHubs.id,
-          actorUri: federatedHubs.actorUri,
-          name: federatedHubs.name,
-          lastSyncAt: federatedHubs.lastSyncAt,
-        })
+      // Stale predicate: lastSyncAt is null or older than the interval. Reused for
+      // both the candidate select and the atomic claim so the claim only succeeds
+      // while the row is still stale (compare-and-claim).
+      const isStale = or(
+        isNull(federatedHubs.lastSyncAt),
+        lt(federatedHubs.lastSyncAt, staleThreshold),
+      );
+
+      // Find accepted, non-hidden hubs that are stale (candidates). We capture the
+      // prior lastSyncAt here (before the claim overwrites it) so first-sync
+      // detection survives the atomic claim below.
+      const candidates = await db
+        .select({ id: federatedHubs.id, lastSyncAt: federatedHubs.lastSyncAt })
         .from(federatedHubs)
         .where(and(
           eq(federatedHubs.status, 'accepted'),
           eq(federatedHubs.isHidden, false),
-          or(
-            isNull(federatedHubs.lastSyncAt),
-            lt(federatedHubs.lastSyncAt, staleThreshold),
-          ),
+          isStale,
         ))
         .limit(MAX_HUBS_PER_CYCLE);
 
-      if (staleHubs.length === 0) return;
+      if (candidates.length === 0) return;
+
+      // Map id -> was-this-a-first-sync (prior lastSyncAt null), captured pre-claim.
+      const wasFirstSync = new Map<string, boolean>(
+        candidates.map((c) => [c.id, c.lastSyncAt === null]),
+      );
+
+      // Atomic claim (mirrors federation-delivery's compare-and-claim): set
+      // lastSyncAt = now() on the selected ids, but only WHERE still stale. On N
+      // replicas selecting the same hubs, exactly one replica's UPDATE matches the
+      // stale predicate per row, so each hub is claimed (and fetched from remotes)
+      // once per cycle instead of N times. RETURNING gives us the rows we won.
+      const candidateIds = candidates.map((c) => c.id);
+      const claimedAt = new Date();
+      const staleHubs = await db
+        .update(federatedHubs)
+        .set({ lastSyncAt: claimedAt })
+        .where(and(
+          inArray(federatedHubs.id, candidateIds),
+          isStale,
+        ))
+        .returning({
+          id: federatedHubs.id,
+          actorUri: federatedHubs.actorUri,
+          name: federatedHubs.name,
+        });
+
+      if (staleHubs.length === 0) return; // another replica claimed them first
 
-      console.log(`[hub-sync] Found ${staleHubs.length} stale hub(s) to sync`);
+      console.log(`[hub-sync] Claimed ${staleHubs.length} stale hub(s) to sync`);
 
       for (const hub of staleHubs) {
         try {
@@ -85,7 +114,7 @@ export default defineNitroPlugin((nitro) => {
           await refreshFederatedHubMetadata(db, hub.id, hub.actorUri);
 
           // Fetch followers to populate members list (first sync or periodic refresh)
-          if (!hub.lastSyncAt) {
+          if (wasFirstSync.get(hub.id)) {
             // First sync — fetch followers to seed the members table
             try {
               const result = await fetchRemoteHubFollowers(db, hub.id, domain);
@@ -105,7 +134,9 @@ export default defineNitroPlugin((nitro) => {
             }
           }
 
-          // Update lastSyncAt
+          // Refresh lastSyncAt to completion time. The atomic claim above already
+          // set it to the claim time (which is what prevents other replicas from
+          // re-claiming); this just advances it to reflect successful completion.
           await db.update(federatedHubs).set({
             lastSyncAt: new Date(),
           }).where(eq(federatedHubs.id, hub.id));

package/server/plugins/notification-email.ts

@@ -11,7 +11,7 @@ import {
   listNotifications,
 } from '@commonpub/server';
 import type { NotificationType } from '@commonpub/server';
-import { users } from '@commonpub/schema';
+import { users, digestRuns } from '@commonpub/schema';
 import { and, isNotNull, eq } from 'drizzle-orm';
 
 export default defineNitroPlugin((nitro) => {
@@ -76,7 +76,9 @@ export default defineNitroPlugin((nitro) => {
     }
   }, 5_000);
 
-  // Track the last date digests were sent to prevent duplicates on server restart during 8am hour
+  // Cheap in-process pre-check to avoid hitting the DB once this replica has already
+  // observed today's digest as claimed. The DB claim (digest_runs) is the authority:
+  // it guarantees exactly-one-replica-wins across N replicas / restarts.
   let lastDigestDate = '';
 
   async function runDigest(siteUrl: string, siteName: string): Promise<void> {
@@ -91,11 +93,28 @@ export default defineNitroPlugin((nitro) => {
 
       if (!isDigestHour) return;
 
-      // Prevent duplicate sends if server restarts during digest hour
+      // Deterministic UTC date key (YYYY-MM-DD). toISOString() is always UTC.
       const todayKey = now.toISOString().slice(0, 10);
+
+      // Cheap pre-check: this replica already knows today's digest is handled.
       if (lastDigestDate === todayKey) return;
+
+      // Atomic cross-replica claim: INSERT today's row, ON CONFLICT DO NOTHING.
+      // Exactly one replica gets a returned row (it won the claim); the rest get
+      // an empty array and bail without sending. Replaces the per-process guard
+      // that sent N duplicate digests on N replicas.
+      const claimed = await db
+        .insert(digestRuns)
+        .values({ digestDate: todayKey })
+        .onConflictDoNothing({ target: digestRuns.digestDate })
+        .returning({ digestDate: digestRuns.digestDate });
+
+      // Record locally regardless of outcome so this replica skips the DB on
+      // subsequent hourly ticks within the same UTC day.
       lastDigestDate = todayKey;
 
+      if (claimed.length === 0) return; // another replica already claimed today
+
       // Find users with digest preferences
       const digestUsers = await db
         .select({

package/server/routes/hubs/[slug]/inbox.ts

@@ -1,5 +1,5 @@
 import { processInboxActivity } from '@commonpub/protocol';
-import { createInboxHandlers } from '@commonpub/server';
+import { createInboxHandlers, recordActivitySeen } from '@commonpub/server';
 import { verifyInboxRequest, assertActorMatchesSigner } from '../../../utils/inbox';
 
 /**
@@ -22,6 +22,18 @@ export default defineEventHandler(async (event) => {
   assertActorMatchesSigner(actorUri, body, 'hub-inbox');
 
   const db = useDB();
+
+  // Replay dedup: claim the verified activity id BEFORE dispatch so a replayed,
+  // validly-signed activity can't double-apply side effects. No id = process
+  // normally. Placed after verification so attacker-chosen ids can't be seeded.
+  const activityId = body.id;
+  if (typeof activityId === 'string' && activityId.length > 0) {
+    const first = await recordActivitySeen(db, activityId);
+    if (!first) {
+      return { status: 'accepted' };
+    }
+  }
+
   const domain = config.instance.domain;
   const slug = getRouterParam(event, 'slug');
   const handlers = createInboxHandlers({ db, domain, hubContext: slug ? { hubSlug: slug } : undefined });

package/server/routes/inbox.ts

@@ -1,5 +1,5 @@
 import { processInboxActivity } from '@commonpub/protocol';
-import { createInboxHandlers } from '@commonpub/server';
+import { createInboxHandlers, recordActivitySeen } from '@commonpub/server';
 import { verifyInboxRequest, assertActorMatchesSigner, extractDomain } from '../utils/inbox';
 
 export default defineEventHandler(async (event) => {
@@ -18,6 +18,19 @@ export default defineEventHandler(async (event) => {
   assertActorMatchesSigner(actorUri, body, 'shared-inbox');
 
   const db = useDB();
+
+  // Replay dedup: claim the verified activity id BEFORE dispatch so a replayed,
+  // validly-signed activity can't double-apply side effects. No id = process
+  // normally (can't dedup what isn't addressable). Placed after verification so
+  // attacker-chosen ids can't be seeded.
+  const activityId = body.id;
+  if (typeof activityId === 'string' && activityId.length > 0) {
+    const first = await recordActivitySeen(db, activityId);
+    if (!first) {
+      return { status: 'accepted' };
+    }
+  }
+
   const runtimeConfig = useRuntimeConfig();
   const domain = extractDomain((runtimeConfig.public?.siteUrl as string) || `https://${config.instance.domain}`);
   const callbacks = createInboxHandlers({ db, domain });

package/server/routes/users/[username]/inbox.ts

@@ -1,5 +1,5 @@
 import { processInboxActivity } from '@commonpub/protocol';
-import { createInboxHandlers } from '@commonpub/server';
+import { createInboxHandlers, recordActivitySeen } from '@commonpub/server';
 import { verifyInboxRequest, assertActorMatchesSigner, extractDomain } from '../../../utils/inbox';
 
 export default defineEventHandler(async (event) => {
@@ -17,6 +17,18 @@ export default defineEventHandler(async (event) => {
   assertActorMatchesSigner(actorUri, body, 'user-inbox');
 
   const db = useDB();
+
+  // Replay dedup: claim the verified activity id BEFORE dispatch so a replayed,
+  // validly-signed activity can't double-apply side effects. No id = process
+  // normally. Placed after verification so attacker-chosen ids can't be seeded.
+  const activityId = body.id;
+  if (typeof activityId === 'string' && activityId.length > 0) {
+    const first = await recordActivitySeen(db, activityId);
+    if (!first) {
+      return { status: 'accepted' };
+    }
+  }
+
   const runtimeConfig = useRuntimeConfig();
   const domain = extractDomain((runtimeConfig.public?.siteUrl as string) || `https://${config.instance.domain}`);
   const callbacks = createInboxHandlers({ db, domain });

package/server/utils/inbox.ts

@@ -4,6 +4,7 @@
  * body size limits, and Date header freshness checks.
  */
 import { verifyHttpSignature, resolveActor } from '@commonpub/protocol';
+import { createSafeActorFetchFn } from '@commonpub/server';
 import type { H3Event } from 'h3';
 
 /** Maximum allowed body size for inbox POSTs (1 MB) */
@@ -97,8 +98,12 @@ export async function verifyInboxRequest(event: H3Event, label: string): Promise
 
   const actorUri = keyId.replace(/#.*$/, '');
 
-  // 4. Resolve actor and public key
-  const actor = await resolveActor(actorUri, fetch);
+  // 4. Resolve actor and public key.
+  // Use the SSRF-pinned fetch (DNS-rebind safe), NOT raw global fetch: actorUri here is
+  // the attacker-controlled keyId resolved BEFORE signature verification, so an
+  // unauthenticated POST /inbox could otherwise drive a server-side GET to internal
+  // addresses (cloud metadata, RFC1918). Audit session 204 — P0.
+  const actor = await resolveActor(actorUri, createSafeActorFetchFn());
   if (!actor?.publicKey?.publicKeyPem) {
     throw createError({ statusCode: 401, statusMessage: 'Could not resolve actor public key' });
   }

package/server/utils/validate.ts

@@ -9,6 +9,13 @@ import type { ZodType } from 'zod';
 const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const SLUG_REGEX = /^[a-z0-9][a-z0-9-]*$/;
 
+/** True when `value` is a syntactically-valid UUID. Use to guard untrusted
+ *  query/body values that feed a uuid SQL bind (a non-uuid string reaching
+ *  the bind throws an unhandled 500). Router params should use `parseParams`. */
+export function isUuid(value: string): boolean {
+  return UUID_REGEX.test(value);
+}
+
 /**
  * Hard ceiling on JSON request bodies (10 MB). Every JSON write route funnels
  * through `parseBody`, so this one guard caps them all. It rejects on the
@@ -33,10 +40,25 @@ type ParamType = 'uuid' | 'slug' | 'string';
 
 /** Parse and validate request body against a Zod schema. Throws 400 on failure, 413 if oversized. */
 export async function parseBody<T>(event: H3Event, schema: ZodType<T>): Promise<T> {
+  // Fast-path: reject on the declared Content-Length before buffering anything.
   const declaredLength = Number(getRequestHeader(event, 'content-length') ?? 0);
   if (Number.isFinite(declaredLength) && declaredLength > MAX_JSON_BODY_BYTES) {
     throw createError({ statusCode: 413, statusMessage: 'Payload too large' });
   }
+
+  // The header is advisory and absent on chunked (Transfer-Encoding: chunked)
+  // requests — a client can stream an unbounded body with no Content-Length and
+  // slip past the fast-path. Read the RAW body once and enforce the cap on the
+  // ACTUAL buffered byte size before JSON.parse. `readBody` reuses this cached
+  // raw body, so there is no double read.
+  const raw: string | Buffer | undefined = await readRawBody(event, false);
+  if (raw != null) {
+    const size = typeof raw === 'string' ? Buffer.byteLength(raw) : raw.length;
+    if (size > MAX_JSON_BODY_BYTES) {
+      throw createError({ statusCode: 413, statusMessage: 'Payload too large' });
+    }
+  }
+
   const body = await readBody(event);
   const parsed = schema.safeParse(body);
   if (!parsed.success) {

package/theme/base.css

@@ -7,6 +7,11 @@
    =========================================== */
 
 :root {
+  /* Theme native UI (date/time pickers, scrollbars, form controls) to the light
+     palette; dark.css overrides to `dark`. Without this, native popups (e.g. the
+     datetime-local calendar) render in the OS default scheme and clash. */
+  color-scheme: light;
+
   /* === SURFACES === */
   --bg: #fafaf9;
   --surface: #ffffff;

package/theme/prose.css

@@ -339,4 +339,24 @@
   text-transform: uppercase;
   letter-spacing: var(--tracking-wide);
 }
+
+/* ===========================================
+   Full-HTML author content (CpubMarkdown format=html)
+   The v-html children carry no scoped styles, so this global, theme-aware
+   baseline keeps un-styled (or var()-based) author HTML readable in BOTH
+   themes. Hardcoded color literals are neutralized at sanitize time
+   (sanitizeRichHtml neutralizeColors), so this baseline shows through.
+   =========================================== */
+.cpub-md-html {
+  color: var(--text);
+  line-height: var(--leading-normal);
+}
+.cpub-md-html a { color: var(--accent); }
+.cpub-md-html h1, .cpub-md-html h2, .cpub-md-html h3,
+.cpub-md-html h4, .cpub-md-html h5, .cpub-md-html h6 { color: var(--text); }
+.cpub-md-html img { max-width: 100%; height: auto; }
+.cpub-md-html hr { border: 0; border-top: var(--border-width-default) solid var(--border); }
+.cpub-md-html blockquote { border-left: 3px solid var(--border); color: var(--text-dim); padding-left: var(--space-4); }
+.cpub-md-html th, .cpub-md-html td { border: var(--border-width-default) solid var(--border); }
+.cpub-md-html pre, .cpub-md-html code { background: var(--surface2); color: var(--text); }
 }

package/theme/stoa-dark.css

@@ -11,6 +11,10 @@
    =========================================== */
 
 [data-theme="stoa-dark"] {
+  /* Theme native UI (date/time pickers, scrollbars) dark — dark.css/agora-dark.css
+     already do this; stoa-dark was missing it, so native controls rendered light. */
+  color-scheme: dark;
+
   /* === SURFACES (warm near-black) === */
   --bg: #15130d;
   --surface: #1f1c14;

package/types/contestBlocks.ts

@@ -0,0 +1,122 @@
+/**
+ * Contest-specific block content shapes (BlockTuple content objects).
+ *
+ * These blocks live ENTIRELY in the layer: the edit component is provided to
+ * BlockCanvas via `BLOCK_COMPONENTS_KEY` (no @commonpub/editor change — the
+ * editor registry is unused; component resolution is `override ?? builtin ??
+ * TextBlock`), and the view component is registered in BlockContentRenderer's
+ * map. Persistence rides the contest `descriptionBlocks`/`rulesBlocks` jsonb
+ * (validated loosely as `BlockTuple[]`), so no registry/schema wiring is needed.
+ */
+
+/** A single judge/mentor card in the `judgesShowcase` block. */
+export interface JudgeShowcaseEntry {
+  name: string;
+  /** Avatar image URL (falls back to the name initial). */
+  avatarUrl?: string;
+  /** Role / affiliation line, e.g. "Lead Judge, ACME Labs". */
+  title?: string;
+  /** Short bio / description. */
+  bio?: string;
+  /** Optional profile or external link (http(s) only when rendered). */
+  link?: string;
+}
+
+/**
+ * `judgesShowcase` block — an editorial judges/mentors showcase for the contest
+ * overview (avatar + name + bio), curated independently of the `contest_judges`
+ * table / Judges tab.
+ */
+export interface JudgesShowcaseContent {
+  /** Optional section heading, e.g. "Meet the Judges". */
+  heading?: string;
+  judges: JudgeShowcaseEntry[];
+}
+
+/** Block type key shared by the edit component (provide map) + the view (renderer map). */
+export const JUDGES_SHOWCASE_TYPE = 'judgesShowcase';
+
+/** A single logo in the `sponsors` block. */
+export interface SponsorLogo {
+  /** Logo image URL (uploaded or pasted). */
+  src: string;
+  /** Accessible name — the organization, used as the img alt. */
+  alt: string;
+  /** Optional outbound link (http(s) only when rendered). */
+  url?: string;
+  /** Optional tier label, e.g. "Gold". Logos sharing a tier render in one group. */
+  tier?: string;
+}
+
+/**
+ * `sponsors` block — a logo wall for partners/sponsors. Flat list of logos with an
+ * optional eyebrow heading; logos that share a `tier` group together (the view
+ * shows the tier labels only when at least one logo is tiered).
+ */
+export interface SponsorsContent {
+  /** Eyebrow heading above the wall, e.g. "Sponsors". */
+  heading?: string;
+  logos: SponsorLogo[];
+}
+
+export const SPONSORS_TYPE = 'sponsors';
+
+/** Tone of a `compareColumns` column — drives its color + per-item icon. */
+export type CompareTone = 'positive' | 'negative' | 'neutral';
+
+/** One column in the `compareColumns` block. */
+export interface CompareColumn {
+  tone: CompareTone;
+  /** Column title, e.g. "Encouraged" / "Out of scope". */
+  title: string;
+  /** Bullet items (plain text). */
+  items: string[];
+}
+
+/**
+ * `compareColumns` block — side-by-side guidance columns (the classic
+ * "Encouraged / Out of scope" or do-vs-don't pattern), with an optional eyebrow,
+ * heading, and a footer note.
+ */
+export interface CompareColumnsContent {
+  /** Eyebrow label above the heading, e.g. "What is in scope". */
+  eyebrow?: string;
+  /** Heading line. */
+  heading?: string;
+  columns: CompareColumn[];
+  /** Optional footer note shown under the columns. */
+  note?: string;
+}
+
+export const COMPARE_COLUMNS_TYPE = 'compareColumns';
+
+/** Visual emphasis of a roadmap node — default (hollow), accent (filled), highlight (finale). */
+export type RoadmapTone = 'default' | 'accent' | 'highlight';
+
+/** One milestone on the `roadmap` timeline. */
+export interface RoadmapItem {
+  /** Free-text date label, e.g. "Jun 30" (organizer-editable, not a real date). */
+  date?: string;
+  title: string;
+  /** Plain-text blurb under the title. */
+  description?: string;
+  /** Optional pill next to the date, e.g. "Mid-term". */
+  badge?: string;
+  tone?: RoadmapTone;
+}
+
+/**
+ * `roadmap` block — a vertical schedule timeline. The edit block can seed its
+ * items from the contest's stages/schedule (one click), then the organizer edits,
+ * reorders, and styles them freely; the saved items are independent of the live
+ * stages (present-how-you-like).
+ */
+export interface RoadmapContent {
+  /** Eyebrow label, e.g. "Key dates, 2026". */
+  eyebrow?: string;
+  /** Heading line, e.g. "The 18-week roadmap". */
+  heading?: string;
+  items: RoadmapItem[];
+}
+
+export const ROADMAP_TYPE = 'roadmap';

package/utils/contestBlocks.ts

@@ -0,0 +1,107 @@
+/**
+ * Helpers for contest content blocks (criteria-bar segment math, the shared
+ * theme-color palette) + the inject key the contest editor uses to feed the
+ * criteria-bar block its rubric. The math is pure/unit-testable in isolation.
+ */
+import type { InjectionKey, Ref } from 'vue';
+import type { RoadmapItem } from '../types/contestBlocks';
+
+/** A contest judging-rubric criterion (mirrors useContestEditor's criteria row). */
+export interface ContestRubricCriterion { label: string; weight?: number; description?: string }
+
+/** ContestEditor `provide`s its live judging criteria under this key so the
+ *  criteria-bar edit block can offer a "use this contest's rubric" auto-fill.
+ *  Absent (null) when the block is used outside the contest editor. */
+export const CONTEST_RUBRIC_KEY: InjectionKey<Ref<ContestRubricCriterion[]>> = Symbol('contestRubric');
+
+/** ContestEditor `provide`s a ready-to-use roadmap derived from the contest's
+ *  effective schedule under this key, so the roadmap block can offer a
+ *  "pull from schedule" seed. Absent (null) outside the contest editor. */
+export const CONTEST_SCHEDULE_KEY: InjectionKey<Ref<RoadmapItem[]>> = Symbol('contestSchedule');
+
+/** 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. */
+export interface RoadmapScheduleDates { startDate?: string; endDate?: string; judgingEndDate?: string }
+
+/** Format an ISO date as a short label ("Jun 30"); '' for empty/invalid input. */
+export function fmtRoadmapDate(iso?: string): string {
+  if (!iso) return '';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '';
+  return d.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+}
+
+/**
+ * Derive roadmap items from the contest's effective timeline: the custom stages
+ * when present, else the core Submissions → Judging → Results flow from the
+ * schedule dates. The `results` kind (and the synthetic finale) get the
+ * `highlight` tone. Pure — the seed the roadmap edit block copies in.
+ */
+export function roadmapFromSchedule(stages: RoadmapStageSource[] | undefined, schedule: RoadmapScheduleDates): RoadmapItem[] {
+  const named = (stages ?? []).filter((s) => (s?.name ?? '').trim());
+  if (named.length) {
+    return named.map((s) => ({
+      date: fmtRoadmapDate(s.startsAt ?? s.endsAt),
+      title: s.name.trim(),
+      description: (s.description ?? '').trim() || undefined,
+      tone: s.kind === 'results' ? 'highlight' : 'default',
+    }));
+  }
+  const items: RoadmapItem[] = [];
+  if (schedule.startDate) items.push({ date: fmtRoadmapDate(schedule.startDate), title: 'Submissions open', tone: 'default' });
+  if (schedule.endDate) items.push({ date: fmtRoadmapDate(schedule.endDate), title: 'Submissions close', tone: 'default' });
+  const judge = schedule.judgingEndDate || schedule.endDate;
+  if (judge) items.push({ date: fmtRoadmapDate(judge), title: 'Judging ends', tone: 'default' });
+  items.push({ title: 'Results announced', tone: 'highlight' });
+  return items;
+}
+
+/**
+ * Theme color tokens segments cycle through (all dark/light-safe `var(--*)`).
+ * Ordered to spread hue across the rotation so adjacent segments stay
+ * distinguishable in a seamless (gap-free) bar — incl. green-accent themes where
+ * accent/teal/green collapse, so those three are kept apart in the order.
+ */
+export const CRITERIA_BAR_PALETTE = ['accent', 'yellow', 'purple', 'teal', 'pink', 'green', 'red'] as const;
+export type CriteriaColorKey = (typeof CRITERIA_BAR_PALETTE)[number];
+
+/** Resolve a segment color: the author's palette key, else a rotation by index.
+ *  Always a theme `var(--*)` so it adapts to light/dark + custom themes. */
+export function criteriaColorVar(key: string | undefined, index = 0): string {
+  const k = key && (CRITERIA_BAR_PALETTE as readonly string[]).includes(key)
+    ? key
+    : CRITERIA_BAR_PALETTE[index % CRITERIA_BAR_PALETTE.length];
+  return `var(--${k})`;
+}
+
+export interface CriteriaBarItem { label: string; weight?: number; color?: string; description?: string }
+export interface CriteriaRow { label: string; weight: number; description?: string; pct: number; colorVar: string; colorKey: string }
+
+/**
+ * Resolve criteria items into legend rows + bar geometry. EVERY labeled item
+ * becomes a row (so the legend lists them all, even 0-weight/holistic ones);
+ * `pct` is each weight's share of the total (the bar fills 100% regardless of
+ * whether weights sum to 100). Colors are assigned by the item's index in the
+ * labeled list so a row's legend swatch always matches its bar segment. The bar
+ * renders `rows.filter(r => r.pct > 0)`.
+ */
+export function criteriaBar(items: CriteriaBarItem[] | undefined): { rows: CriteriaRow[]; total: number } {
+  const labeled = (items ?? []).filter((i) => (i?.label ?? '').trim());
+  const total = labeled.reduce((s, i) => s + Math.max(0, Number(i?.weight) || 0), 0);
+  const rows = labeled.map((i, idx) => {
+    const key = i.color && (CRITERIA_BAR_PALETTE as readonly string[]).includes(i.color)
+      ? i.color
+      : CRITERIA_BAR_PALETTE[idx % CRITERIA_BAR_PALETTE.length]!;
+    const w = Math.max(0, Number(i.weight) || 0);
+    return {
+      label: i.label.trim(),
+      weight: w,
+      description: (i.description ?? '').trim() || undefined,
+      pct: total > 0 ? Math.round((w / total) * 1000) / 10 : 0,
+      colorVar: `var(--${key})`,
+      colorKey: key,
+    };
+  });
+  return { rows, total };
+}

package/utils/contestBody.ts

@@ -0,0 +1,25 @@
+import { markdownToBlockTuples, type BlockTuple } from '@commonpub/editor';
+
+/**
+ * Seed the contest body block editor (overview/rules): prefer existing
+ * `BlockTuple[]`; otherwise convert the legacy markdown/html body — the
+ * convert-on-edit pattern (CLAUDE rule #4), so editing a legacy contest doesn't
+ * lose its content. Legacy HTML is preserved VERBATIM in a single markdown block
+ * (lossless) rather than lossily re-parsed; markdown is parsed into real blocks.
+ */
+export function seedBodyBlocks(
+  blocks: unknown[] | null | undefined,
+  legacy?: string | null,
+  legacyFormat?: 'markdown' | 'html' | null,
+): BlockTuple[] {
+  if (Array.isArray(blocks) && blocks.length) return blocks as BlockTuple[];
+  const text = (legacy ?? '').trim();
+  if (!text) return [];
+  if (legacyFormat === 'html') return [['markdown', { content: text }]];
+  try {
+    const parsed = markdownToBlockTuples(text);
+    return parsed.length ? parsed : [['markdown', { content: text }]];
+  } catch {
+    return [['markdown', { content: text }]];
+  }
+}