@commonpub/layer 0.81.0 → 0.83.0

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 }]];
+  }
+}

package/utils/contestStages.ts

@@ -154,11 +154,73 @@ export function withTemplateFieldRemoved(stages: ContestStage[], i: number, fi:
   return withTemplate(stages, i, cur);
 }
 
+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
+ * `select` drops `options`; leaving `agreement` drops `terms`/`termsFormat`/
+ * `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 };
+  patch.options = type === 'select' ? (field.options?.length ? field.options : [{ value: '', label: '' }]) : undefined;
+  if (type === 'agreement') {
+    patch.mustAccept = field.mustAccept ?? true;
+  } else {
+    patch.terms = undefined;
+    patch.termsFormat = undefined;
+    patch.mustAccept = undefined;
+  }
+  if (type === 'address') patch.pii = true;
+  return withTemplateFieldSet(stages, i, fi, patch);
+}
+
+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: '' }] });
+}
+
+export function withTemplateOptionSet(
+  stages: ContestStage[],
+  i: number,
+  fi: number,
+  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 });
+}
+
+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) });
+}
+
 /** Human label for each template field type (for the editor dropdown). */
 export const TEMPLATE_FIELD_TYPE_LABEL: Record<ContestSubmissionTemplateField['type'], string> = {
   text: 'Short text',
   textarea: 'Long text',
   url: 'Link (URL)',
+  email: 'Email address',
+  number: 'Number',
+  select: 'Dropdown (select)',
+  checkbox: 'Checkbox',
+  date: 'Date',
+  agreement: 'Agreement (terms to accept)',
+  address: 'Mailing address',
 };
 
 /** FontAwesome icon (no `fa-solid` prefix) for each stage kind. */

package/utils/contestSubmission.ts

@@ -0,0 +1,97 @@
+import type { ContestSubmissionTemplateField } from '@commonpub/schema';
+
+// Client-side helpers for the entrant submission form (the per-stage artifact
+// form + the proposal form share these). The SERVER (validateSubmissionFields)
+// is the authoritative validator; these only drive UX (required gating, the
+// payload shape) so the two surfaces behave identically.
+
+/** Markers a checkbox/agreement value counts as accepted/checked. */
+const TRUTHY = new Set(['true', 'on', '1', 'yes', 'accepted', 'checked']);
+
+export function isChecked(value: string | undefined): boolean {
+  return TRUTHY.has((value ?? '').trim().toLowerCase());
+}
+
+/** Structured mailing-address subfields (stored JSON-encoded in the value). */
+export const ADDRESS_SUBFIELDS = [
+  { key: 'line1', label: 'Address line 1' },
+  { key: 'line2', label: 'Address line 2' },
+  { key: 'city', label: 'City' },
+  { key: 'region', label: 'State / region' },
+  { key: 'postal', label: 'Postal code' },
+  { key: 'country', label: 'Country' },
+] as const;
+
+export type AddressValue = Partial<Record<(typeof ADDRESS_SUBFIELDS)[number]['key'], string>>;
+
+export function parseAddress(value: string | undefined): AddressValue {
+  if (!value) return {};
+  try {
+    const o = JSON.parse(value);
+    return o && typeof o === 'object' && !Array.isArray(o) ? (o as AddressValue) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Serialize an address to a compact JSON string, or '' when entirely empty. */
+export function serializeAddress(addr: AddressValue): string {
+  const cleaned: AddressValue = {};
+  for (const { key } of ADDRESS_SUBFIELDS) {
+    const v = (addr[key] ?? '').trim();
+    if (v) cleaned[key] = v;
+  }
+  return Object.keys(cleaned).length ? JSON.stringify(cleaned) : '';
+}
+
+/** True when a field's value is "filled" for required purposes (type-aware). */
+export function isFieldFilled(field: ContestSubmissionTemplateField, value: string | undefined): boolean {
+  const v = (value ?? '').trim();
+  if (field.type === 'checkbox' || field.type === 'agreement') return isChecked(v);
+  if (field.type === 'address') return Object.keys(parseAddress(v)).length > 0;
+  return v.length > 0;
+}
+
+/**
+ * The labels of fields that block submission: required-but-empty fields, plus
+ * any must-accept agreement that isn't accepted. Mirrors the server's gate so
+ * the entrant sees the problem before the round-trip.
+ */
+export function blockingFields(
+  template: ContestSubmissionTemplateField[],
+  values: Record<string, string>,
+): string[] {
+  const out: string[] = [];
+  for (const f of template) {
+    const filled = isFieldFilled(f, values[f.key]);
+    if (f.type === 'agreement') {
+      if ((f.required || f.mustAccept !== false) && !filled) out.push(f.label);
+    } else if (f.required && !filled) {
+      out.push(f.label);
+    }
+  }
+  return out;
+}
+
+/**
+ * Build the submit payload: trimmed values, omitting blanks. Checkbox/agreement
+ * normalize to 'true'/'false'; address passes its JSON through; everything else
+ * is the trimmed string. Empty optional fields are dropped.
+ */
+export function buildSubmissionPayload(
+  template: ContestSubmissionTemplateField[],
+  values: Record<string, string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const f of template) {
+    const raw = (values[f.key] ?? '').trim();
+    if (f.type === 'checkbox' || f.type === 'agreement') {
+      // Only send a positive marker (the server treats absent as not-accepted).
+      if (isChecked(raw)) out[f.key] = 'true';
+      else if (f.type === 'checkbox' && raw) out[f.key] = 'false';
+    } else if (raw) {
+      out[f.key] = raw;
+    }
+  }
+  return out;
+}

package/utils/datetime.ts

@@ -0,0 +1,45 @@
+/**
+ * Local-time conversion for `<input type="datetime-local">`.
+ *
+ * A datetime-local control speaks the operator's LOCAL wall-clock with no zone.
+ * The common idiom `new Date(iso).toISOString().slice(0, 16)` is WRONG: toISOString
+ * is UTC, so the value shown is shifted by the local offset and the time the
+ * operator picks isn't the time that gets stored. These helpers build the input
+ * value from the date's LOCAL components and parse it back as local, so the
+ * round-trip is offset-correct in every timezone.
+ */
+
+const pad = (n: number): string => String(n).padStart(2, '0');
+
+/** An ISO instant rendered as `YYYY-MM-DDTHH:mm` in the viewer's local zone (the input value). */
+export function toLocalInput(iso?: string | null): string {
+  if (!iso) return '';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '';
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+/** A `YYYY-MM-DDTHH:mm` local wall-clock value parsed to an ISO instant. Empty/invalid -> undefined. */
+export function fromLocalInput(local?: string | null): string | undefined {
+  if (!local) return undefined;
+  // A datetime-local string carries no offset, so the runtime parses it as LOCAL.
+  const d = new Date(local);
+  return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+}
+
+/**
+ * An ISO instant as a short human date in the VIEWER's local zone, e.g.
+ * "Aug 1, 2026" (or "Aug 1" with `{ year: false }`). One formatter for every
+ * contest date surface (hero, sidebar timeline, entry rows).
+ *
+ * It is timezone-dependent (the local calendar day differs by zone), so any caller
+ * that renders server-side MUST gate it behind a client `mounted` flag — otherwise
+ * the server's TZ and the viewer's disagree on hydration and Vue won't rectify it.
+ * Empty / invalid input -> ''.
+ */
+export function formatLocalDate(iso?: string | null, opts?: { year?: boolean }): string {
+  if (!iso) return '';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '';
+  return d.toLocaleDateString('en-US', { month: 'short', day: 'numeric', ...(opts?.year === false ? {} : { year: 'numeric' }) });
+}

package/utils/projectBlocks.ts

@@ -0,0 +1,162 @@
+/**
+ * projectBlocks — pure parsers that turn a project's BlockTuple content into
+ * the structured shapes the ProjectView tabs render (BOM parts, build steps,
+ * code snippets, download files, table-of-contents headings).
+ *
+ * Extracted verbatim from ProjectView.vue's inline computeds (session 206) so
+ * the parsing is unit-tested independently of the component. Each function
+ * accepts the raw `content` value (which may be undefined, a legacy markdown
+ * string, or a BlockTuple[]) and returns [] for anything that is not an array
+ * of blocks — matching the component's original guards exactly.
+ */
+
+export interface PartItem {
+  name: string;
+  quantity: number;
+  productId?: string;
+  notes?: string;
+}
+
+export interface BuildStep {
+  number: number;
+  title: string;
+  children: Array<[string, Record<string, unknown>]>;
+  time?: string;
+}
+
+export interface CodeSnippet {
+  language: string;
+  filename: string;
+  code: string;
+}
+
+export interface FileItem {
+  name: string;
+  url: string;
+  size?: string;
+}
+
+export interface TocEntry {
+  id: string;
+  text: string;
+  level: number;
+}
+
+type Block = [string, Record<string, unknown>];
+
+/** Narrow raw content to a block array, or [] when it is not one. */
+function asBlocks(blocks: unknown): Block[] {
+  return Array.isArray(blocks) ? (blocks as Block[]) : [];
+}
+
+/** Slugify heading text into a stable anchor id (lowercase, dash-separated). */
+export function headingSlug(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '');
+}
+
+/** Flatten every `partsList` block into a BOM parts list. */
+export function extractParts(blocks: unknown): PartItem[] {
+  const items: PartItem[] = [];
+  for (const [type, data] of asBlocks(blocks)) {
+    if (type === 'partsList' && Array.isArray(data.parts)) {
+      for (const part of data.parts as Array<Record<string, unknown>>) {
+        items.push({
+          name: (part.name as string) || 'Unknown',
+          quantity: (part.qty as number) ?? (part.quantity as number) ?? 1,
+          productId: part.productId as string | undefined,
+          notes: (part.notes as string) || '',
+        });
+      }
+    }
+  }
+  return items;
+}
+
+/** Collect `buildStep` blocks, migrating the legacy instructions+image shape into children. */
+export function extractBuildSteps(blocks: unknown): BuildStep[] {
+  const steps: BuildStep[] = [];
+  let stepNum = 0;
+  for (const [type, data] of asBlocks(blocks)) {
+    if (type !== 'buildStep') continue;
+    stepNum++;
+    // Migrate old format (instructions + image) to children
+    let children: Array<[string, Record<string, unknown>]> = [];
+    if (data.children && Array.isArray(data.children) && data.children.length > 0) {
+      children = data.children as Array<[string, Record<string, unknown>]>;
+    } else {
+      const instructions = data.instructions as string | undefined;
+      if (instructions && instructions.trim()) {
+        const html = instructions.startsWith('<') ? instructions : `<p>${instructions}</p>`;
+        children.push(['paragraph', { html }]);
+      }
+      const image = data.image as string | undefined;
+      if (image && image.trim()) {
+        children.push(['image', { src: image, alt: `Step ${stepNum}`, caption: '' }]);
+      }
+    }
+    steps.push({
+      number: (data.stepNumber as number) || stepNum,
+      title: (data.title as string) || `Step ${stepNum}`,
+      children,
+      time: data.time as string | undefined,
+    });
+  }
+  return steps;
+}
+
+/** Collect `code_block`/`codeBlock` snippets for the Code tab. */
+export function extractCodeBlocks(blocks: unknown): CodeSnippet[] {
+  const snippets: CodeSnippet[] = [];
+  for (const [type, data] of asBlocks(blocks)) {
+    if (type === 'code_block' || type === 'codeBlock') {
+      snippets.push({
+        language: (data.language as string) || '',
+        filename: (data.filename as string) || '',
+        code: (data.code as string) || '',
+      });
+    }
+  }
+  return snippets;
+}
+
+/** Flatten every `downloads` block into a flat file list for the Files tab. */
+export function extractDownloadFiles(blocks: unknown): FileItem[] {
+  const files: FileItem[] = [];
+  for (const [type, data] of asBlocks(blocks)) {
+    if (type === 'downloads' && Array.isArray(data.files)) {
+      for (const file of data.files as Array<Record<string, unknown>>) {
+        files.push({
+          name: (file.name as string) || 'Unknown',
+          url: (file.url as string) || '',
+          size: (file.size as string) || '',
+        });
+      }
+    }
+  }
+  return files;
+}
+
+/** Build a table of contents from `heading` blocks (HTML stripped, slugified ids). */
+export function extractTocEntries(blocks: unknown): TocEntry[] {
+  const entries: TocEntry[] = [];
+  for (const [type, data] of asBlocks(blocks)) {
+    if (type === 'heading' && data.text) {
+      const raw = String(data.text);
+      const label = raw.replace(/<[^>]+>/g, '');
+      if (label.trim()) {
+        entries.push({
+          // Slug the RAW text: BlockHeadingView.vue (and ArticleView.vue) render
+          // the anchor id by slugging the unstripped text, so the TOC id must match
+          // or getElementById()/scroll-spy can't find the heading.
+          id: headingSlug(raw),
+          text: label.trim(),
+          level: (data.level as number) ?? 2,
+        });
+      }
+    }
+  }
+  return entries;
+}