create-portfoliable 1.0.3

package/scripts/scaffold-case.mjs

@@ -0,0 +1,460 @@
+#!/usr/bin/env node
+// File: scripts/scaffold-case.mjs
+// Purpose: Generate a starter markdown case for a Portfoliable consumer app.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+import fs from 'node:fs';
+import path from 'node:path';
+import { readLocaleConfigFromI18nConfig, resolveI18nConfigPath } from '../templates/scripts/i18n-config-utils.mjs';
+
+// MARK: DEFAULTS
+// Defines default output path used when no known case root can be resolved.
+const DEFAULT_OUTPUT = 'src/content/cases/my-case/case.md';
+// Defines default case name used when no name is provided.
+const DEFAULT_NAME = 'My Case';
+// Defines candidate case roots in priority order for local repo and consumer apps.
+const DEFAULT_CASES_ROOTS = ['templates/src/content/cases', 'src/content/cases'];
+
+// MARK: DEFAULT CASE TEMPLATE
+// Centralized defaults used when scaffolding new cases.
+const DEFAULT_CASE_TEMPLATE = {
+  caseOrder: 100,
+  socialImage: 'https://images.unsplash.com/photo-1518770660439-4636190af475?q=80&w=1200&h=675&auto=format&fit=contain&bg=111111',
+  titleShow: true,
+  shortDescShow: true,
+  shortDescByLocale: {
+    en: 'Write a short summary for this case.',
+    pt: 'Escreva um resumo curto para este case.',
+    default: 'Write a short summary for this case.'
+  },
+  readTimeByLocale: {
+    default: '3 min'
+  },
+  kickerByLocale: {
+    en: '2026 - Starter Project',
+    pt: '2026 - Projeto Iniciador',
+    default: '2026 - Starter Project'
+  },
+  thumbSrc: 'https://images.unsplash.com/photo-1518770660439-4636190af475?q=80&w=1200&auto=format&fit=crop',
+  thumbCategory: 'mobile',
+  thumbBrand: 'apple',
+  thumbModel: 'Apple iPhone 17',
+  thumbColor: 'iPhone 17 - White - Portrait',
+  showCover: true,
+  showSummary: true,
+  showReader: true,
+  showToc: true,
+  showNavigator: true,
+  showPlayer: true,
+  summaryByLocale: {
+    en: 'Add an executive summary for this case.',
+    pt: 'Adicione um resumo executivo para este case.',
+    default: 'Add an executive summary for this case.'
+  },
+  summaryPropsTextByLocale: {
+    en: 'Add concise impact details, launch scope, and operational confidence outcomes.',
+    pt: 'Adicione detalhes de impacto, escopo de lancamento e resultados de confianca operacional.',
+    default: 'Add concise impact details, launch scope, and operational confidence outcomes.'
+  },
+  summaryPropsLabelHeaderByLocale: {
+    en: 'Case Snapshot',
+    pt: 'Snapshot do Case',
+    default: 'Case Snapshot'
+  },
+  summaryPropsAriaLabelByLocale: {
+    en: 'Case summary with key metrics',
+    pt: 'Resumo do case com metricas-chave',
+    default: 'Case summary with key metrics'
+  },
+  audioLabelByLocale: {
+    en: 'Case Audio Summary',
+    pt: 'Resumo em Audio do Case',
+    default: 'Case Audio Summary'
+  },
+  customButtonPrimaryLabelByLocale: {
+    en: 'GitHub',
+    pt: 'GitHub',
+    default: 'GitHub'
+  },
+  customButtonPrimaryTooltipByLocale: {
+    en: 'Open GitHub profile',
+    pt: 'Abrir perfil do GitHub',
+    default: 'Open GitHub profile'
+  },
+  customButtonPrimaryUrl: 'https://github.com/your-handle',
+  customButtonPrimaryVariant: 'primary',
+  customButtonPrimaryIcon: 'github',
+  customButtonPrimaryIconVariant: 'outline',
+  customButtonPrimaryEnabled: true,
+  visibility: {
+    web: true,
+    crawlers: true,
+    ai: true,
+    locales: {}
+  },
+  isProtected: false,
+  isUnlocked: false,
+  social: {
+    share: { enabled: true, icon: 'share', 'icon-variant': 'outline' },
+    linkedin: { enabled: true, icon: 'linkedin', 'icon-variant': 'outline' },
+    x: { enabled: true, icon: 'x', 'icon-variant': 'outline' },
+    facebook: { enabled: true, icon: 'facebook', 'icon-variant': 'outline' }
+  },
+  actions: {
+    primary: { enabled: false, variant: 'primary', icon: 'play', 'icon-variant': 'fill' },
+    secondary: { enabled: false, variant: 'secondary', icon: 'link', 'icon-variant': 'outline' },
+    tertiary: { enabled: false, variant: 'tertiary' }
+  },
+  customButtons: []
+};
+
+// Convert user input into a URL-safe slug.
+function toSlug(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'my-case';
+}
+
+// Normalize a freeform case name into title case.
+function toTitle(value) {
+  // Cleans separators and duplicate whitespace in user-provided title text.
+  const cleaned = String(value || '')
+    .trim()
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ');
+
+  if (!cleaned) return DEFAULT_NAME;
+
+  return cleaned
+    .split(' ')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+// MARK: ARGUMENT PARSING
+// Read CLI flags from the current process argv.
+function parseArgs(argv) {
+  // Extracts script args excluding node executable and script path.
+  const args = argv.slice(2);
+  // Initializes parser output with defaults.
+  const options = {
+    outFile: '',
+    name: DEFAULT_NAME,
+    force: false
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    // Reads current argument token under evaluation.
+    const arg = args[i];
+
+    if (arg === '--out' && args[i + 1]) {
+      options.outFile = args[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--name' && args[i + 1]) {
+      options.name = args[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--force') {
+      options.force = true;
+    }
+  }
+
+  return options;
+}
+
+// Resolves available case roots for template and consumer layouts.
+function resolveCasesRoots(cwd) {
+  return DEFAULT_CASES_ROOTS
+    .map((relativeRoot) => path.resolve(cwd, relativeRoot))
+    .filter((absoluteRoot) => fs.existsSync(absoluteRoot) && fs.statSync(absoluteRoot).isDirectory());
+}
+
+  // Computes default output markdown path from first discovered cases root.
+function resolveDefaultOutFile(cwd, name) {
+  const caseSlug = toSlug(name);
+  const roots = resolveCasesRoots(cwd);
+  if (roots.length > 0) {
+    const target = path.join(roots[0], caseSlug, 'case.md');
+    return path.relative(cwd, target);
+  }
+
+  return DEFAULT_OUTPUT;
+}
+
+// Derives case slug from output path patterns or fallback case name.
+function resolveCaseSlugFromOutput(outFile, name) {
+  const basename = path.basename(outFile || '');
+  if (basename.toLowerCase() === 'case.md') {
+    return toSlug(path.basename(path.dirname(outFile || '')) || name);
+  }
+
+  return toSlug(path.basename(outFile || '', '.md') || name);
+}
+
+// Serializes one config field while preserving indentation for multiline values.
+function formatConfigField(key, value, indent = '  ') {
+  const serialized = JSON.stringify(value, null, 2);
+  if (!serialized.includes('\n')) {
+    return `${indent}"${key}": ${serialized},`;
+  }
+
+  const lines = serialized.split('\n');
+  const output = [`${indent}"${key}": ${lines[0]}`];
+  lines.slice(1).forEach((line) => {
+    output.push(`${indent}${line}`);
+  });
+  output[output.length - 1] = `${output[output.length - 1]},`;
+  return output.join('\n');
+}
+
+// Builds grouped config comment block injected at the top of scaffolded case markdown.
+function formatCaseConfigBlock(caseConfig) {
+  const lines = [
+    '<!-- config',
+    '{',
+    '  // Identity',
+    formatConfigField('id', caseConfig.id),
+    formatConfigField('caseOrder', caseConfig.caseOrder),
+    formatConfigField('slugByLocale', caseConfig.slugByLocale),
+    formatConfigField('socialImage', caseConfig.socialImage),
+    '',
+    '  // Localized Metadata',
+    formatConfigField('title', caseConfig.title),
+    formatConfigField('shortDesc', caseConfig.shortDesc),
+    formatConfigField('readTime', caseConfig.readTime),
+    formatConfigField('kicker', caseConfig.kicker),
+    '',
+    '  // Thumbnail and Cover',
+    '  // Available thumbCategory values: desktop, mobile, tablet, wearable',
+    formatConfigField('thumbSrc', caseConfig.thumbSrc),
+    formatConfigField('thumbCategory', caseConfig.thumbCategory),
+    formatConfigField('thumbBrand', caseConfig.thumbBrand),
+    formatConfigField('thumbModel', caseConfig.thumbModel),
+    formatConfigField('thumbColor', caseConfig.thumbColor),
+    formatConfigField('showCover', caseConfig.showCover),
+    '',
+    '  // Summary Experience (edit here or in summary:start blocks below)',
+    formatConfigField('showSummary', caseConfig.showSummary),
+    formatConfigField('summary', caseConfig.summary),
+    formatConfigField('summaryProps', caseConfig.summaryProps),
+    '',
+    '  // Reader Experience',
+    formatConfigField('showReader', caseConfig.showReader),
+    formatConfigField('showToc', caseConfig.showToc),
+    formatConfigField('showNavigator', caseConfig.showNavigator),
+    '',
+    '  // Audio Experience',
+    formatConfigField('audioLabel', caseConfig.audioLabel),
+    formatConfigField('audioSrc', caseConfig.audioSrc),
+    formatConfigField('showPlayer', caseConfig.showPlayer),
+    '',
+    '  // Visibility and Protection',
+    formatConfigField('visibility', caseConfig.visibility),
+    formatConfigField('isProtected', caseConfig.isProtected),
+    formatConfigField('isUnlocked', caseConfig.isUnlocked),
+    '',
+    '  // Social',
+    formatConfigField('social', caseConfig.social),
+    '',
+    '  // Actions',
+    formatConfigField('actions', caseConfig.actions),
+    '',
+    '  // Custom Buttons',
+    formatConfigField('customButtons', caseConfig.customButtons),
+    '}',
+    '-->'
+  ];
+
+  return lines.join('\n');
+}
+
+// Build the markdown scaffold body used for new cases.
+function buildTemplate({ name, slug, localeCodes }) {
+  // Derives normalized title for localized title fields.
+  const title = toTitle(name);
+  // Derives normalized slug for id and localized route slug fields.
+  const cleanSlug = toSlug(slug || name);
+  // Builds localized maps with locale-specific values and default fallback support.
+  const localizedValue = (defaultsByLocale = {}) => {
+    return Object.fromEntries(localeCodes.map((localeCode) => {
+      const value = defaultsByLocale[localeCode] ?? defaultsByLocale.default ?? '';
+      return [localeCode, value];
+    }));
+  };
+
+  const caseConfig = {
+    id: cleanSlug,
+    caseOrder: DEFAULT_CASE_TEMPLATE.caseOrder,
+    slugByLocale: localizedValue({ default: cleanSlug }),
+    socialImage: localizedValue({ default: DEFAULT_CASE_TEMPLATE.socialImage }),
+    title: {
+      show: DEFAULT_CASE_TEMPLATE.titleShow,
+      ...localizedValue({ default: title })
+    },
+    shortDesc: {
+      show: DEFAULT_CASE_TEMPLATE.shortDescShow,
+      ...localizedValue(DEFAULT_CASE_TEMPLATE.shortDescByLocale)
+    },
+    readTime: localizedValue(DEFAULT_CASE_TEMPLATE.readTimeByLocale),
+    kicker: localizedValue(DEFAULT_CASE_TEMPLATE.kickerByLocale),
+    thumbSrc: localizedValue({ default: DEFAULT_CASE_TEMPLATE.thumbSrc }),
+    thumbCategory: DEFAULT_CASE_TEMPLATE.thumbCategory,
+    thumbBrand: DEFAULT_CASE_TEMPLATE.thumbBrand,
+    thumbModel: DEFAULT_CASE_TEMPLATE.thumbModel,
+    thumbColor: DEFAULT_CASE_TEMPLATE.thumbColor,
+    showCover: DEFAULT_CASE_TEMPLATE.showCover,
+    showSummary: DEFAULT_CASE_TEMPLATE.showSummary,
+    summary: localizedValue(DEFAULT_CASE_TEMPLATE.summaryByLocale),
+    summaryProps: {
+      text: localizedValue(DEFAULT_CASE_TEMPLATE.summaryPropsTextByLocale),
+      active: true,
+      labelHeader: localizedValue(DEFAULT_CASE_TEMPLATE.summaryPropsLabelHeaderByLocale),
+      showMetrics: true,
+      ariaLabel: localizedValue(DEFAULT_CASE_TEMPLATE.summaryPropsAriaLabelByLocale),
+      metrics: [
+        {
+          value: '',
+          label: localizedValue({ default: '' }),
+          variant: 'default',
+          ariaLabel: localizedValue({ default: '' })
+        }
+      ]
+    },
+    showReader: DEFAULT_CASE_TEMPLATE.showReader,
+    showToc: DEFAULT_CASE_TEMPLATE.showToc,
+    showNavigator: DEFAULT_CASE_TEMPLATE.showNavigator,
+    audioLabel: localizedValue(DEFAULT_CASE_TEMPLATE.audioLabelByLocale),
+    audioSrc: localizedValue({ default: '' }),
+    showPlayer: DEFAULT_CASE_TEMPLATE.showPlayer,
+    visibility: { ...DEFAULT_CASE_TEMPLATE.visibility },
+    isProtected: DEFAULT_CASE_TEMPLATE.isProtected,
+    isUnlocked: DEFAULT_CASE_TEMPLATE.isUnlocked,
+    social: {
+      share: {
+        ...DEFAULT_CASE_TEMPLATE.social.share,
+        tooltip: localizedValue({ default: '' })
+      },
+      linkedin: {
+        ...DEFAULT_CASE_TEMPLATE.social.linkedin,
+        tooltip: localizedValue({ default: '' })
+      },
+      x: {
+        ...DEFAULT_CASE_TEMPLATE.social.x,
+        tooltip: localizedValue({ default: '' })
+      },
+      facebook: {
+        ...DEFAULT_CASE_TEMPLATE.social.facebook,
+        tooltip: localizedValue({ default: '' })
+      },
+      links: {
+        linkedin: '',
+        x: '',
+        facebook: ''
+      }
+    },
+    actions: {
+      primary: {
+        ...DEFAULT_CASE_TEMPLATE.actions.primary,
+        label: localizedValue({ en: 'Watch Launch Video', pt: 'Assistir Video do Lancamento', default: 'Watch Launch Video' }),
+        tooltip: localizedValue({ en: 'Open launch walkthrough video', pt: 'Abrir video de apresentacao do lancamento', default: 'Open launch walkthrough video' }),
+        url: localizedValue({ default: '' }),
+        videoSrc: localizedValue({ default: '' }),
+        vttSrc: localizedValue({ default: '' }),
+        imageAlt: localizedValue({ default: '' }),
+        ariaLabel: localizedValue({ default: '' })
+      },
+      secondary: {
+        ...DEFAULT_CASE_TEMPLATE.actions.secondary,
+        label: localizedValue({ en: 'Repository', pt: 'Repositorio', default: 'Repository' }),
+        tooltip: localizedValue({ en: 'Open implementation repository', pt: 'Abrir repositorio de implementacao', default: 'Open implementation repository' }),
+        url: localizedValue({ default: '' }),
+        imageAlt: localizedValue({ default: '' }),
+        ariaLabel: localizedValue({ default: '' })
+      },
+      tertiary: {
+        ...DEFAULT_CASE_TEMPLATE.actions.tertiary,
+        label: localizedValue({ en: 'Live Demo', pt: 'Demo Ao Vivo', default: 'Live Demo' }),
+        tooltip: localizedValue({ en: 'Open interactive demo', pt: 'Abrir demo interativa', default: 'Open interactive demo' }),
+        url: localizedValue({ default: '' }),
+        'has-image': false,
+        'image-src': '',
+        'image-alt': '',
+        imageAlt: localizedValue({ default: '' }),
+        ariaLabel: localizedValue({ default: '' })
+      }
+    },
+    customButtons: [
+      {
+        label: localizedValue(DEFAULT_CASE_TEMPLATE.customButtonPrimaryLabelByLocale),
+        tooltip: localizedValue(DEFAULT_CASE_TEMPLATE.customButtonPrimaryTooltipByLocale),
+        url: DEFAULT_CASE_TEMPLATE.customButtonPrimaryUrl,
+        variant: DEFAULT_CASE_TEMPLATE.customButtonPrimaryVariant,
+        icon: DEFAULT_CASE_TEMPLATE.customButtonPrimaryIcon,
+        'icon-variant': DEFAULT_CASE_TEMPLATE.customButtonPrimaryIconVariant,
+        enabled: DEFAULT_CASE_TEMPLATE.customButtonPrimaryEnabled,
+        imageAlt: localizedValue({ default: '' }),
+        ariaLabel: localizedValue({ default: '' })
+      }
+    ]
+  };
+
+  const sectionBlock = localeCodes.map((localeCode) => {
+    if (localeCode === 'pt') {
+      return `<!-- lang:${localeCode} -->\n## Problema\nDescreva o problema em portugues.\n\n## Solucao\nDescreva a solucao em portugues.`;
+    }
+
+    return `<!-- lang:${localeCode} -->\n## Problem\nDescribe the problem in ${localeCode}.\n\n## Solution\nDescribe the solution in ${localeCode}.`;
+  }).join('\n\n');
+
+  return `${formatCaseConfigBlock(caseConfig)}\n\n${sectionBlock}\n`;
+}
+
+// Create the scaffold case file unless the destination already exists.
+export function runCaseScaffold(options = {}) {
+  // Resolves working directory used for output file path calculation.
+  const cwd = options.cwd || process.cwd();
+  // Resolves output filename using option or context-aware default fallback.
+  const outFile = options.outFile || resolveDefaultOutFile(cwd, options.name || DEFAULT_NAME);
+  // Resolves case display name using option or default fallback.
+  const name = options.name || DEFAULT_NAME;
+  const caseSlug = resolveCaseSlugFromOutput(outFile, name);
+  // Coerces force flag to explicit boolean.
+  const force = Boolean(options.force);
+  // Resolves absolute output path for scaffold file.
+  const outputPath = path.resolve(cwd, outFile);
+  const i18nConfigPath = resolveI18nConfigPath(cwd);
+  const localeConfig = readLocaleConfigFromI18nConfig(i18nConfigPath);
+  const templateLocaleFallback = Object.keys(DEFAULT_CASE_TEMPLATE.shortDescByLocale || {})
+    .filter((localeCode) => localeCode !== 'default');
+  const localeCodes = Array.isArray(localeConfig.supportedLocales) && localeConfig.supportedLocales.length > 0
+    ? localeConfig.supportedLocales
+    : templateLocaleFallback;
+
+  if (fs.existsSync(outputPath) && !force) {
+    console.log(`[scaffold-case] Nothing to create. Case already exists: ${outputPath}`);
+    return 0;
+  }
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, buildTemplate({ name, slug: caseSlug, localeCodes }), 'utf8');
+  console.log(`[scaffold-case] Created starter case file: ${outputPath}`);
+  return 0;
+}
+
+// MARK: SCRIPT ENTRYPOINT
+// Executes argument parsing and scaffold run when script is invoked directly.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  // Parses CLI options from current process arguments.
+  const options = parseArgs(process.argv);
+  // Runs scaffolder and captures process exit code.
+  const exitCode = runCaseScaffold(options);
+  process.exit(exitCode);
+}

package/scripts/scaffold-consumer.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// File: scripts/scaffold-consumer.mjs
+// Purpose: Generate a starter consumer cases file for Portfoliable projects.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+import fs from 'node:fs';
+import path from 'node:path';
+
+// MARK: DEFAULTS
+// Defines default output filename for scaffolded consumer cases module.
+const DEFAULT_OUTPUT = 'portfolio-cases.template.js';
+
+// Defines full starter template content for scaffolded consumer cases module.
+const TEMPLATE_CONTENT = `export const portfolioCases = [
+  {
+    id: 'my-first-case',
+    slugByLocale: { en: 'my-first-case', pt: 'meu-primeiro-case' },
+    title: { en: 'My First Case', pt: 'Meu Primeiro Case' },
+    shortDesc: {
+      en: 'Describe the project in one sentence.',
+      pt: 'Descreva o projeto em uma frase.'
+    },
+    readTime: { en: '3 min', pt: '3 min' },
+    year: { en: '2026 - Personal Project', pt: '2026 - Projeto Pessoal' },
+    thumbSrc: {
+      en: 'assets/thumbs/en/my-first-case.avif',
+      pt: 'assets/thumbs/pt/my-first-case.avif'
+    },
+    repositoryUrl: 'https://github.com/your-user/your-repo',
+    liveUrl: 'https://example.com',
+    videoSrc: {
+      en: 'assets/videos/en/my-first-case.mp4',
+      pt: 'assets/videos/pt/my-first-case.mp4'
+    },
+    vttSrc: {
+      en: 'assets/subtitles/en/my-first-case.vtt',
+      pt: 'assets/subtitles/pt/my-first-case.vtt'
+    },
+    desc: {
+      en: '<p class="p1">Write your story here in English.</p>',
+      pt: '<p class="p1">Escreva sua historia aqui em portugues.</p>'
+    },
+    descRecruiter: {
+      en: '<p class="p1">Add your technical recruiter summary here.</p>',
+      pt: '<p class="p1">Adicione seu resumo tecnico para recrutadores aqui.</p>'
+    }
+  }
+];
+`;
+
+// Write the scaffold file, refusing to overwrite unless explicitly requested.
+export function runScaffold(options = {}) {
+  // Resolves working directory for output path resolution.
+  const cwd = options.cwd || process.cwd();
+  // Resolves output filename from options or default fallback.
+  const outFile = options.outFile || DEFAULT_OUTPUT;
+  // Coerces overwrite flag to explicit boolean.
+  const force = Boolean(options.force);
+  // Resolves absolute output file path.
+  const outputPath = path.resolve(cwd, outFile);
+
+  if (fs.existsSync(outputPath) && !force) {
+    console.error(`[scaffold] Refusing to overwrite existing file: ${outputPath}`);
+    console.error('[scaffold] Use --force to overwrite.');
+    return 1;
+  }
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, TEMPLATE_CONTENT, 'utf8');
+  console.log(`[scaffold] Created starter cases file: ${outputPath}`);
+  return 0;
+}
+
+// MARK: SCRIPT ENTRYPOINT
+// Executes scaffold flow when script is invoked directly.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  // Resolves index of --out option token in argv.
+  const outIndex = process.argv.findIndex((arg) => arg === '--out');
+  // Resolves force flag from argv.
+  const force = process.argv.includes('--force');
+  // Resolves outFile argument value with default fallback.
+  const outFile = outIndex >= 0 ? process.argv[outIndex + 1] : DEFAULT_OUTPUT;
+  // Executes scaffold and captures resulting exit code.
+  const exitCode = runScaffold({ outFile, force });
+  process.exit(exitCode);
+}

package/scripts/smoke-homeview.mjs

@@ -0,0 +1,133 @@
+// File: create-portfoliable/scripts/smoke-homeview.mjs
+// Purpose: Smoke-test build output to confirm HomeView, sample content, and device assets are emitted.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+// MARK: PATH CONSTANTS
+// Resolves the script absolute filename for deterministic project-root path computation.
+const __filename = fileURLToPath(import.meta.url);
+// Resolves the directory containing this script.
+const __dirname = path.dirname(__filename);
+// Resolves the package root used as the working directory for smoke commands.
+const projectRoot = path.resolve(__dirname, '..');
+// Resolves the build output directory validated by this smoke test.
+const distDir = path.join(projectRoot, 'dist');
+
+// MARK: ERROR HANDLING
+// Terminates the smoke test with a consistent prefixed error message.
+function fail(message) {
+  console.error(`[smoke] ${message}`);
+  process.exit(1);
+}
+
+// MARK: BUILD STEP
+// Executes a production build before assertions so smoke checks inspect fresh artifacts.
+function runBuild() {
+  console.log('[smoke] Running build...');
+  // Runs the package build command and forwards process output directly to the terminal.
+  const build = spawnSync('npm', ['run', 'build'], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    shell: process.platform === 'win32'
+  });
+
+  if (build.status !== 0) {
+    fail('Build failed.');
+  }
+}
+
+// MARK: BUNDLE DISCOVERY
+// Locates the newest index bundle produced by Vite and returns its source text for assertions.
+function readMainBundle() {
+  // Resolves the generated assets directory that contains hashed JS bundles.
+  const assetsDir = path.join(distDir, 'assets');
+  if (!fs.existsSync(assetsDir)) {
+    fail('Missing dist/assets after build.');
+  }
+
+  // Reads all generated asset filenames.
+  const files = fs.readdirSync(assetsDir);
+  // Filters for the main app bundle naming convention emitted by Vite.
+  const jsBundles = files.filter((file) => file.startsWith('index-') && file.endsWith('.js'));
+
+  if (jsBundles.length === 0) {
+    fail('Could not find main JS bundle in dist/assets.');
+  }
+
+  // Selects the most recently modified main bundle in case multiple artifacts are present.
+  const newestBundle = jsBundles
+    .map((file) => ({
+      file,
+      mtimeMs: fs.statSync(path.join(assetsDir, file)).mtimeMs
+    }))
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)[0].file;
+
+  // Loads bundle text so feature markers can be validated with string assertions.
+  const bundlePath = path.join(assetsDir, newestBundle);
+  return fs.readFileSync(bundlePath, 'utf8');
+}
+
+// MARK: ASSERTION HELPER
+// Verifies a marker string exists in the tested output and aborts with a clear reason if missing.
+function assertIncludes(haystack, needle, message) {
+  if (!haystack.includes(needle)) {
+    fail(message);
+  }
+}
+
+// MARK: SMOKE ORCHESTRATION
+// Runs build, inspects emitted bundle/assets, and validates HomeView/CaseView route expectations.
+function main() {
+  runBuild();
+
+  if (!fs.existsSync(path.join(distDir, 'index.html'))) {
+    fail('dist/index.html not found.');
+  }
+
+  // Loads emitted main bundle text for marker assertions.
+  const bundleText = readMainBundle();
+
+  // HomeView template is mounted through ds-home-view.
+  assertIncludes(bundleText, 'ds-home-view', 'HomeView marker not found in bundle.');
+
+  // CaseView template must exist for in-app Home -> Case transitions.
+  assertIncludes(bundleText, 'ds-case-view', 'CaseView marker not found in bundle.');
+
+  // Route transition helpers should be present in the runtime shell bundle.
+  assertIncludes(bundleText, '_transitionToView', 'Route transition helper not found in bundle.');
+  assertIncludes(bundleText, 'data-route-direction', 'Route direction marker not found in bundle.');
+  assertIncludes(bundleText, '_isNativeMorphPreferredPair', 'Native morph policy helper not found in bundle.');
+  assertIncludes(bundleText, 'native-running', 'Native transition debug marker not found in bundle.');
+  assertIncludes(bundleText, 'manual-fallback', 'Manual fallback debug marker not found in bundle.');
+  assertIncludes(bundleText, 'home->player', 'Direct Home -> Player transition marker not found in bundle.');
+  assertIncludes(bundleText, 'player->home', 'Direct Player -> Home transition marker not found in bundle.');
+
+  // Template case metadata markers should survive bundling regardless of sample title wording.
+  assertIncludes(bundleText, 'thumbCategory', 'Template case metadata marker not found in bundle.');
+  assertIncludes(bundleText, 'thumbBrand', 'Template case metadata brand marker not found in bundle.');
+
+  // Thumbnail frame fallback asset should be part of build outputs.
+  const hasDeviceFrameAsset = fs
+    .readdirSync(path.join(distDir, 'assets'))
+    .some((file) => {
+      if (!file.endsWith('.avif')) return false;
+      const normalized = file.toLowerCase();
+      return (
+        normalized.startsWith('iphone-12-black-') ||
+        (normalized.includes('iphone') && normalized.includes('12') && normalized.includes('black'))
+      );
+    });
+
+  if (!hasDeviceFrameAsset) {
+    fail('Expected thumbnail device frame asset was not generated.');
+  }
+
+  console.log('[smoke] HomeView and gallery smoke checks passed.');
+}
+
+main();