create-portfoliable 1.0.3

package/templates/scripts/validate-content.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+// File: scripts/validate-content.mjs
+// Purpose: Validate template case markdown before dev, build, or preview.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseCaseMarkdownWithDiagnostics } from '../src/parser/markdown.js';
+import { readLocaleConfigFromI18nConfig, resolveI18nConfigPath } from './i18n-config-utils.mjs';
+
+// MARK: LAYOUT RESOLUTION
+// Resolves project paths for template-repo mode and generated-app mode.
+function resolveProjectLayout(cwd = process.cwd()) {
+  const templateCasesDir = path.join(cwd, 'templates', 'src', 'content', 'cases');
+  const hasTemplateCases = fs.existsSync(templateCasesDir) && fs.statSync(templateCasesDir).isDirectory();
+
+  if (hasTemplateCases) {
+    return {
+      mode: 'template',
+      root: cwd,
+      casesDir: templateCasesDir
+    };
+  }
+
+  return {
+    mode: 'consumer',
+    root: cwd,
+    casesDir: path.join(cwd, 'src', 'content', 'cases')
+  };
+}
+
+// Collect every markdown case file from the cases directory.
+function listMarkdownFiles(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    return [];
+  }
+
+  const files = [];
+
+  // Recursively walks nested case folders to collect markdown files.
+  const walk = (currentDir) => {
+    fs.readdirSync(currentDir, { withFileTypes: true }).forEach((entry) => {
+      const nextPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(nextPath);
+        return;
+      }
+
+      if (entry.name.endsWith('.md')) {
+        files.push(nextPath);
+      }
+    });
+  };
+
+  walk(dirPath);
+  return files;
+}
+
+// Reads UTF-8 file content from disk.
+function readUtf8(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+// Converts absolute file path to repository-relative path for diagnostics.
+function toRelPath(filePath, rootDir) {
+  return path.relative(rootDir, filePath);
+}
+
+// Guard against empty or non-string values.
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+// Check localized values that must define both language variants.
+function isLocalizedObject(value, localeCodes) {
+  if (!value || typeof value !== 'object') return false;
+  return localeCodes.every((localeCode) => isNonEmptyString(value[localeCode]));
+}
+
+// Accept only URLs or project-local asset paths for link-like fields.
+function isValidUrlOrAssetPath(value) {
+  if (!isNonEmptyString(value)) return false;
+  // Normalizes value before URL/path pattern checks.
+  const normalized = value.trim();
+  return (
+    normalized.startsWith('http://')
+    || normalized.startsWith('https://')
+    || normalized.startsWith('assets/')
+    || normalized.startsWith('./')
+    || normalized.startsWith('../')
+    || normalized.startsWith('/')
+  );
+}
+
+// Surface non-fatal content quality warnings for case metadata.
+function collectCaseLevelWarnings(caseData, contextLabel, supportedLocales) {
+  // Collects warning-level findings that should not fail builds.
+  const warnings = [];
+  const localeCodes = Array.isArray(caseData?.locales) && caseData.locales.length > 0
+    ? caseData.locales
+    : supportedLocales;
+  // Accepts localized maps only when at least one locale contains non-empty text.
+  const hasAnyLocalizedValue = (value) => {
+    if (!value || typeof value !== 'object') return false;
+    return Object.values(value).some((entry) => isNonEmptyString(entry));
+  };
+
+  if (isNonEmptyString(caseData?.repositoryUrl) && !isValidUrlOrAssetPath(caseData.repositoryUrl)) {
+    warnings.push(`${contextLabel}: repositoryUrl should be a valid URL or asset-style path.`);
+  }
+
+  if (isNonEmptyString(caseData?.liveUrl) && !isValidUrlOrAssetPath(caseData.liveUrl)) {
+    warnings.push(`${contextLabel}: liveUrl should be a valid URL or asset-style path.`);
+  }
+
+  if (hasAnyLocalizedValue(caseData?.videoSrc) && !isLocalizedObject(caseData.videoSrc, localeCodes)) {
+    warnings.push(`${contextLabel}: videoSrc should define localized values for locales: ${localeCodes.join(', ')} when provided.`);
+  }
+
+  if (hasAnyLocalizedValue(caseData?.vttSrc) && !isLocalizedObject(caseData.vttSrc, localeCodes)) {
+    warnings.push(`${contextLabel}: vttSrc should define localized values for locales: ${localeCodes.join(', ')} when provided.`);
+  }
+
+  if (hasAnyLocalizedValue(caseData?.audioSrc) && !isLocalizedObject(caseData.audioSrc, localeCodes)) {
+    warnings.push(`${contextLabel}: audioSrc should define localized values for locales: ${localeCodes.join(', ')} when provided.`);
+  }
+
+  if (isNonEmptyString(caseData?.id) && !/^[a-z0-9-]+$/.test(caseData.id)) {
+    warnings.push(`${contextLabel}: id should use lowercase kebab-case (letters, numbers, hyphens).`);
+  }
+
+  if (caseData?.slugByLocale && typeof caseData.slugByLocale === 'object') {
+    Object.entries(caseData.slugByLocale).forEach(([localeCode, slugValue]) => {
+      if (!isNonEmptyString(slugValue)) return;
+      if (!/^[a-z0-9-]+$/.test(slugValue)) {
+        warnings.push(`${contextLabel}: slugByLocale.${localeCode} should use lowercase kebab-case (letters, numbers, hyphens).`);
+      }
+    });
+  }
+
+  if (isNonEmptyString(caseData?.caseOrder) && !/^\d+$/.test(String(caseData.caseOrder).trim())) {
+    warnings.push(`${contextLabel}: caseOrder should be a positive integer (for example: caseOrder: 10).`);
+  }
+
+  return warnings;
+}
+
+// Detect duplicate ids and slugs across all parsed case files.
+function collectCrossFileErrors(parsedEntries) {
+  // Collects cross-file fatal validation errors.
+  const errors = [];
+  // Maps case ID values to first defining file.
+  const idToFile = new Map();
+  const localizedSlugToFile = new Map();
+
+  parsedEntries.forEach(({ filePath, caseData }) => {
+    // Reads case id for duplicate-id detection.
+    const id = caseData?.id;
+    if (isNonEmptyString(id)) {
+      if (idToFile.has(id)) {
+        errors.push(`${filePath}: duplicate id '${id}'. First defined in ${idToFile.get(id)}.`);
+      } else {
+        idToFile.set(id, filePath);
+      }
+    }
+
+    const slugByLocale = caseData?.slugByLocale && typeof caseData.slugByLocale === 'object'
+      ? caseData.slugByLocale
+      : {};
+    Object.entries(slugByLocale).forEach(([localeCode, localizedSlug]) => {
+      if (!isNonEmptyString(localizedSlug)) return;
+      const collisionKey = `${String(localeCode).trim().toLowerCase()}::${localizedSlug}`;
+      if (localizedSlugToFile.has(collisionKey)) {
+        errors.push(`${filePath}: duplicate localized slug '${localizedSlug}' for locale '${localeCode}'. First defined in ${localizedSlugToFile.get(collisionKey)}.`);
+      } else {
+        localizedSlugToFile.set(collisionKey, filePath);
+      }
+    });
+  });
+
+  return errors;
+}
+
+// Run the complete content validation pass and report errors or warnings.
+export function runValidation(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const layout = resolveProjectLayout(cwd);
+  const i18nConfigPath = resolveI18nConfigPath(cwd);
+  const localeConfig = readLocaleConfigFromI18nConfig(i18nConfigPath);
+  const supportedLocales = localeConfig.supportedLocales;
+  const defaultLocale = localeConfig.defaultLocale;
+
+  // Loads markdown files to validate.
+  const files = listMarkdownFiles(layout.casesDir);
+
+  if (files.length === 0) {
+    const emptyPathLabel = layout.mode === 'template'
+      ? 'templates/src/content/cases'
+      : 'src/content/cases';
+    console.warn(`[validate-content] No markdown files found in ${emptyPathLabel}.`);
+    return 0;
+  }
+
+  // Collects parser/contract errors across all files.
+  const allErrors = [];
+  // Collects warning-level quality checks across all files.
+  const allWarnings = [];
+  // Stores successfully parsed case entries for cross-file checks.
+  const parsedEntries = [];
+
+  files.forEach((filePath) => {
+    // Loads raw markdown file content.
+    const rawText = readUtf8(filePath);
+    // Computes relative path used in diagnostic output.
+    const relPath = toRelPath(filePath, layout.root);
+    // Parses case markdown and returns structured errors/case data.
+    const { caseData, errors } = parseCaseMarkdownWithDiagnostics(rawText, {
+      filePath: relPath,
+      locales: supportedLocales,
+      defaultLocale: defaultLocale
+    });
+    allErrors.push(...errors);
+
+    if (caseData) {
+      parsedEntries.push({ filePath: relPath, caseData });
+      allWarnings.push(...collectCaseLevelWarnings(caseData, relPath, supportedLocales));
+    }
+  });
+
+  allErrors.push(...collectCrossFileErrors(parsedEntries));
+
+  if (allErrors.length === 0) {
+    if (allWarnings.length > 0) {
+      console.warn('[validate-content] WARN: content checks passed with warnings:');
+      allWarnings.forEach((message) => {
+        console.warn(`- ${message}`);
+      });
+    }
+    console.log('[validate-content] OK: all case markdown files are valid.');
+    return 0;
+  }
+
+  console.error('[validate-content] ERROR: found content validation issues:');
+  allErrors.forEach((message) => {
+    console.error(`- ${message}`);
+  });
+
+  return 1;
+}
+
+// Runs validation when script is invoked directly from command line.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  // Captures exit code from validation run.
+  const exitCode = runValidation();
+  process.exit(exitCode);
+}

package/templates/scripts/validate-protection.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// File: scripts/validate-protection.mjs
+// Purpose: Validate PHP protection contract before dev/build/preview/smoke runs.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseCaseMarkdownWithDiagnostics } from '../src/parser/markdown.js';
+import { readLocaleConfigFromI18nConfig, resolveI18nConfigPath } from './i18n-config-utils.mjs';
+
+// MARK: PATH RESOLUTION
+// Resolves project paths for template-repo mode and generated-app mode.
+function resolveProjectLayout(cwd = process.cwd()) {
+  const templateRoot = path.join(cwd, 'templates');
+  const hasTemplateCases = fs.existsSync(path.join(templateRoot, 'src', 'content', 'cases'));
+
+  if (hasTemplateCases) {
+    return {
+      mode: 'template',
+      root: cwd,
+      casesDir: path.join(templateRoot, 'src', 'content', 'cases'),
+      designConfigPath: path.join(templateRoot, 'configs', 'portfoliable.design.config.js'),
+      phpEndpointPath: path.join(templateRoot, 'public', 'api', 'unlock-case.php'),
+      passwordConfigPath: path.join(templateRoot, 'public', 'api', 'password.config.json'),
+      passwordExamplePath: path.join(templateRoot, 'public', 'api', 'password.config.example.json')
+    };
+  }
+
+  return {
+    mode: 'consumer',
+    root: cwd,
+    casesDir: path.join(cwd, 'src', 'content', 'cases'),
+    designConfigPath: path.join(cwd, 'configs', 'portfoliable.design.config.js'),
+    phpEndpointPath: path.join(cwd, 'public', 'api', 'unlock-case.php'),
+    passwordConfigPath: path.join(cwd, 'public', 'api', 'password.config.json'),
+    passwordExamplePath: path.join(cwd, 'public', 'api', 'password.config.example.json')
+  };
+}
+
+// MARK: VALIDATION HELPERS
+// Collects markdown files recursively from a directory tree.
+function listMarkdownFiles(dirPath) {
+  if (!fs.existsSync(dirPath)) return [];
+  const files = [];
+
+  // Walks nested directories to discover all markdown case files.
+  const walk = (currentDir) => {
+    fs.readdirSync(currentDir, { withFileTypes: true }).forEach((entry) => {
+      const nextPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(nextPath);
+        return;
+      }
+      if (entry.name.endsWith('.md')) {
+        files.push(nextPath);
+      }
+    });
+  };
+
+  walk(dirPath);
+  return files;
+}
+
+// Reads JSON content from disk for password config checks.
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+// Converts absolute paths to repository-relative labels for diagnostics.
+function toRel(filePath, rootDir) {
+  return path.relative(rootDir, filePath);
+}
+
+// Extracts configured unlock endpoint from design config source text.
+function parseUnlockEndpoint(configText) {
+  const match = configText.match(/unlockEndpoint\s*:\s*['\"]([^'\"]+)['\"]/);
+  return match ? String(match[1]).trim() : '';
+}
+
+// Validates supported password hash formats and rejects template placeholders.
+function isRecognizedPasswordHash(value) {
+  const hash = String(value || '');
+  if (!hash) return false;
+  if (hash.includes('replace') || hash.includes('generated-hash')) return false;
+  return hash.startsWith('$argon2id$') || hash.startsWith('$argon2i$') || hash.startsWith('$2y$') || hash.startsWith('$2b$');
+}
+
+// MARK: VALIDATION ENTRYPOINT
+// Validates unlock endpoint and password hash records for protected cases.
+export function runProtectionValidation(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const layout = resolveProjectLayout(cwd);
+  const i18nConfigPath = resolveI18nConfigPath(cwd);
+  const localeConfig = readLocaleConfigFromI18nConfig(i18nConfigPath);
+  const supportedLocales = localeConfig.supportedLocales;
+  const defaultLocale = localeConfig.defaultLocale;
+
+  const errors = [];
+
+  const caseFiles = listMarkdownFiles(layout.casesDir);
+  const protectedCaseIds = [];
+
+  caseFiles.forEach((filePath) => {
+    const relPath = toRel(filePath, layout.root);
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const { caseData, errors: parseErrors } = parseCaseMarkdownWithDiagnostics(raw, {
+      filePath: relPath,
+      locales: supportedLocales,
+      defaultLocale: defaultLocale
+    });
+
+    if (parseErrors.length > 0 || !caseData) {
+      return;
+    }
+
+    if (caseData.isProtected === true) {
+      protectedCaseIds.push(caseData.id);
+    }
+  });
+
+  if (protectedCaseIds.length === 0) {
+    console.log('[validate-protection] OK: no protected cases enabled.');
+    return 0;
+  }
+
+  if (!fs.existsSync(layout.designConfigPath)) {
+    errors.push(`${toRel(layout.designConfigPath, layout.root)} is missing.`);
+  } else {
+    const configText = fs.readFileSync(layout.designConfigPath, 'utf8');
+    const unlockEndpoint = parseUnlockEndpoint(configText);
+    if (!unlockEndpoint) {
+      errors.push(`${toRel(layout.designConfigPath, layout.root)} must define protection.unlockEndpoint.`);
+    } else if (!unlockEndpoint.includes('/api/unlock-case.php')) {
+      errors.push(`${toRel(layout.designConfigPath, layout.root)} unlockEndpoint must point to /api/unlock-case.php for PHP self-host parity.`);
+    }
+  }
+
+  if (!fs.existsSync(layout.phpEndpointPath)) {
+    errors.push(`${toRel(layout.phpEndpointPath, layout.root)} is missing.`);
+  }
+
+  if (!fs.existsSync(layout.passwordConfigPath)) {
+    errors.push(`${toRel(layout.passwordConfigPath, layout.root)} is missing. Copy ${toRel(layout.passwordExamplePath, layout.root)} and add hashes for protected cases.`);
+  } else {
+    let config = null;
+    try {
+      config = readJson(layout.passwordConfigPath);
+    } catch {
+      errors.push(`${toRel(layout.passwordConfigPath, layout.root)} is not valid JSON.`);
+    }
+
+    if (config) {
+      const cases = config?.cases && typeof config.cases === 'object' ? config.cases : null;
+      if (!cases) {
+        errors.push(`${toRel(layout.passwordConfigPath, layout.root)} must contain a cases object.`);
+      } else {
+        protectedCaseIds.forEach((caseId) => {
+          const record = cases[caseId];
+          const hash = record?.hash;
+          if (!record || typeof record !== 'object') {
+            errors.push(`${toRel(layout.passwordConfigPath, layout.root)} is missing cases.${caseId}.hash`);
+            return;
+          }
+          if (!isRecognizedPasswordHash(hash)) {
+            errors.push(`${toRel(layout.passwordConfigPath, layout.root)} has invalid hash format for cases.${caseId}.hash`);
+          }
+        });
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error('[validate-protection] ERROR:');
+    errors.forEach((error) => console.error(`- ${error}`));
+    return 1;
+  }
+
+  console.log(`[validate-protection] OK: PHP unlock protection is configured for ${protectedCaseIds.length} protected case(s).`);
+  return 0;
+}
+
+// MARK: SCRIPT ENTRYPOINT
+// CLI entrypoint for protection validation checks.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exit(runProtectionValidation());
+}

package/templates/src/cases/index.js

@@ -0,0 +1,188 @@
+// File: create-portfoliable/templates/src/cases/index.js
+// Purpose: Load and normalize markdown cases for generated consumer apps.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+import { parseCaseMarkdownWithDiagnostics } from '../parser/markdown.js';
+import { DEFAULT_LOCALE, SUPPORTED_LOCALES } from '../../configs/i18n/i18n.config.js';
+
+// MARK: LOCALIZATION NORMALIZATION
+// Converts a value into canonical localized shape with optional fallback object.
+function toLocalized(value, fallback, localeCodes = SUPPORTED_LOCALES) {
+  const locales = Array.isArray(localeCodes) && localeCodes.length > 0
+    ? localeCodes
+    : SUPPORTED_LOCALES;
+
+  const fallbackValueByLocale = (localeCode) => {
+    if (fallback && typeof fallback === 'object' && typeof fallback[localeCode] === 'string') {
+      return fallback[localeCode];
+    }
+    if (fallback && typeof fallback === 'object' && typeof fallback[DEFAULT_LOCALE] === 'string') {
+      return fallback[DEFAULT_LOCALE];
+    }
+    if (typeof fallback === 'string') {
+      return fallback;
+    }
+    return '';
+  };
+
+  if (typeof value === 'string') {
+    return Object.fromEntries(locales.map((localeCode) => [localeCode, value]));
+  }
+
+  if (value && typeof value === 'object') {
+    const localized = Object.fromEntries(locales.map((localeCode) => {
+      const raw = value[localeCode];
+      if (typeof raw === 'string') {
+        return [localeCode, raw];
+      }
+
+      const defaultRaw = value[DEFAULT_LOCALE];
+      if (typeof defaultRaw === 'string') {
+        return [localeCode, defaultRaw];
+      }
+
+      return [localeCode, fallbackValueByLocale(localeCode)];
+    }));
+
+    Object.keys(value).forEach((key) => {
+      if (locales.includes(key)) return;
+      localized[key] = value[key];
+    });
+
+    return localized;
+  }
+
+  return Object.fromEntries(locales.map((localeCode) => [localeCode, fallbackValueByLocale(localeCode)]));
+}
+
+// Parses manual gallery order from markdown metadata.
+function parseCaseOrder(value) {
+  if (value === null || value === undefined || value === '') return Number.POSITIVE_INFINITY;
+
+  const parsed = Number.parseInt(String(value).trim(), 10);
+  if (!Number.isFinite(parsed)) return Number.POSITIVE_INFINITY;
+  return parsed;
+}
+
+function normalizeSummaryProps(value, localeCodes = SUPPORTED_LOCALES) {
+  const summaryProps = value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+
+  return {
+    ...summaryProps,
+    text: toLocalized(summaryProps.text, '', localeCodes),
+    labelHeader: toLocalized(summaryProps.labelHeader, '', localeCodes),
+    ariaLabel: toLocalized(summaryProps.ariaLabel, '', localeCodes),
+    active: typeof summaryProps.active === 'boolean' ? summaryProps.active : false,
+    showMetrics: typeof summaryProps.showMetrics === 'boolean' ? summaryProps.showMetrics : false
+  };
+}
+
+// Normalizes one parsed markdown case into the starter app runtime contract.
+function normalizeMarkdownCase(markdownCase) {
+  const localeCodes = Array.isArray(markdownCase?.locales) && markdownCase.locales.length > 0
+    ? markdownCase.locales
+    : SUPPORTED_LOCALES;
+
+  return {
+    ...markdownCase,
+    id: markdownCase.id,
+    caseOrder: parseCaseOrder(markdownCase.caseOrder),
+    title: toLocalized(markdownCase.title, '', localeCodes),
+    shortDesc: toLocalized(markdownCase.shortDesc, '', localeCodes),
+    readTime: toLocalized(markdownCase.readTime, '', localeCodes),
+    kicker: toLocalized(markdownCase.kicker ?? markdownCase.year, '', localeCodes),
+    thumbSrc: toLocalized(markdownCase.thumbSrc, '', localeCodes),
+    desc: toLocalized(markdownCase.desc, '', localeCodes),
+    summary: toLocalized(markdownCase.summary, '', localeCodes),
+    summaryProps: normalizeSummaryProps(markdownCase.summaryProps, localeCodes),
+    descRecruiter: toLocalized(markdownCase.descRecruiter, markdownCase.desc, localeCodes),
+    locales: localeCodes,
+    display: {
+      showSummary: Boolean(markdownCase?.display?.showSummary),
+      showReader: markdownCase?.display?.showReader !== false,
+      showCover: markdownCase?.display?.showCover !== false,
+      showPlayer: markdownCase?.display?.showPlayer !== false,
+      showToc: Boolean(markdownCase?.display?.showToc),
+      showNavigator: markdownCase?.display?.showNavigator !== false
+    }
+  };
+}
+
+// MARK: MARKDOWN CONTENT LOADING
+// Loads markdown modules, parses cases, and aggregates diagnostics for console output.
+function loadMarkdownCases() {
+  // Eagerly imports raw case markdown for startup-time parsing and validation.
+  const modules = import.meta.glob('../content/cases/*.md', {
+    eager: true,
+    import: 'default',
+    query: '?raw'
+  });
+
+  const nestedModules = import.meta.glob('../content/cases/**/*.md', {
+    eager: true,
+    import: 'default',
+    query: '?raw'
+  });
+
+  const allModules = {
+    ...nestedModules,
+    ...modules
+  };
+
+  // Collects parser diagnostics encountered across all markdown files.
+  const diagnostics = [];
+
+  // Parses all imported markdown files and returns valid caseData entries.
+  const parsedCases = Object.entries(allModules)
+    .map(([filePath, rawText]) => {
+      // Parses one markdown module and returns case payload plus diagnostics.
+      const result = parseCaseMarkdownWithDiagnostics(rawText, {
+        filePath,
+        locales: SUPPORTED_LOCALES,
+        defaultLocale: DEFAULT_LOCALE
+      });
+      if (result.errors.length > 0) {
+        diagnostics.push(...result.errors);
+      }
+      return result.caseData;
+    })
+    .filter(Boolean);
+
+  // Prints parser diagnostics as warnings without aborting app bootstrap.
+  if (diagnostics.length > 0) {
+    console.warn('[portfoliable] Content validation warnings:');
+    diagnostics.forEach((message) => console.warn(`- ${message}`));
+  }
+
+  return parsedCases;
+}
+
+// MARK: PUBLIC API
+// Returns normalized portfolio case records for template-generated app runtime.
+export function getPortfolioCases() {
+  // Loads all parsed markdown case entries.
+  const markdownCases = loadMarkdownCases();
+
+  if (markdownCases.length === 0) {
+    console.warn('[portfoliable] No markdown cases were loaded from src/content/cases.');
+  }
+
+  // Normalizes and sorts cases by optional manual order before runtime render.
+  return markdownCases
+    .map((markdownCase, sourceIndex) => ({
+      sourceIndex,
+      caseData: normalizeMarkdownCase(markdownCase)
+    }))
+    .sort((a, b) => {
+      const orderDelta = a.caseData.caseOrder - b.caseData.caseOrder;
+      if (Number.isFinite(orderDelta) && orderDelta !== 0) return orderDelta;
+      return a.sourceIndex - b.sourceIndex;
+    })
+    .map((entry) => entry.caseData);
+}
+
+// Exports eagerly loaded case list used by template bootstrap.
+export const portfolioCases = getPortfolioCases();