@ohos-ports/slides-grab 1.5.0-beta.0

package/src/ohos-browser-bridge.cjs

@@ -0,0 +1,272 @@
+/**
+ * OHOS Browser Bridge — Launch system Chromium browser via hdc + connect via CDP
+ *
+ * Replaces playwright's chromium.launch() on HarmonyOS.
+ * Supports: Haitai browser (Chromium M132), Chrome 鸿蒙版, custom browsers.
+ *
+ * Based on browser-auto-migration (gitcode.com/zhenghongfei):
+ *   1. hdc shell aa force-stop (clean stale process)
+ *   2. hdc shell aa start --ps cmdArgs "--remote-debugging-port=PORT ..."
+ *   3. Wait for CDP endpoint (HTTP poll /json/version)
+ *   4. chromium.connectOverCDP(wsEndpoint)
+ */
+
+const { execFileSync } = require('child_process');
+const http = require('http');
+
+// ─── Browser registry ────────────────────────────────────────────────────
+// Supports multiple Chromium-based browsers on HarmonyOS
+const CHANNEL_MAP = {
+  chrome:         { pkg: 'com.haitai.htbrowser',     ability: 'EntryAbility' },
+  'chrome-beta':  { pkg: 'com.huawei.ohos_chromium', ability: 'BrowserAbility' },
+};
+
+const ENV_MAP = {
+  haitai: { pkg: 'com.haitai.htbrowser',     ability: 'EntryAbility' },
+  chrome: { pkg: 'com.huawei.ohos_chromium',  ability: 'BrowserAbility' },
+};
+
+const DEFAULT_BROWSER = { pkg: 'com.haitai.htbrowser', ability: 'EntryAbility' };
+
+function resolveBrowser(options = {}) {
+  // 1. Explicit bundle name
+  if (options.harmonyBundleName) {
+    return { pkg: options.harmonyBundleName, ability: options.harmonyAbilityName || 'EntryAbility' };
+  }
+  // 2. Channel mapping (chrome / chrome-beta)
+  if (options.channel && CHANNEL_MAP[options.channel]) {
+    return CHANNEL_MAP[options.channel];
+  }
+  // 3. Environment variable (HARMONY_BROWSER=haitai|chrome)
+  const env = process.env.HARMONY_BROWSER;
+  if (env && ENV_MAP[env]) {
+    return ENV_MAP[env];
+  }
+  // 4. Default
+  return DEFAULT_BROWSER;
+}
+
+// ─── Chromium launch flags ──────────────────────────────────────────────
+const BOOL_FLAGS = [
+  'disable-extensions', 'disable-default-apps', 'no-first-run',
+  'no-default-browser-check', 'disable-background-networking',
+  'disable-client-side-phishing-detection', 'disable-popup-blocking',
+  'disable-prompt-on-repost', 'disable-breakpad', 'disable-hang-monitor',
+  'disable-ipc-flooding-protection', 'metrics-recording-only', 'disable-sync',
+  'disable-search-engine-choice-screen', 'disable-background-timer-throttling',
+  'disable-renderer-backgrounding', 'disable-backgrounding-occluded-windows',
+  'disable-field-trial-config', 'disable-component-update', 'disable-dev-shm-usage',
+  'no-service-autorun', 'disable-infobars', 'allow-file-access-from-files',
+  'enable-automation', 'allow-pre-commit-input',
+];
+
+const DISABLED_FEATURES = [
+  'AvoidUnnecessaryBeforeUnloadCheckSync', 'DestroyProfileOnBrowserClose',
+  'DialMediaRouteProvider', 'GlobalMediaControls', 'HttpsUpgrades',
+  'LensOverlay', 'MediaRouter', 'PaintHolding',
+  'ThirdPartyStoragePartitioning', 'Translate', 'AutoDeElevate',
+  'RenderDocument', 'OptimizationHints',
+].join(',');
+
+// ─── hdc ────────────────────────────────────────────────────────────────
+function getHdcPath() {
+  // Try standard HarmonyOS path first, then env var, then PATH
+  try { require('fs').accessSync('/data/service/hnp/bin/hdc'); return '/data/service/hnp/bin/hdc'; } catch {}
+  return process.env.HDC_PATH || 'hdc';
+}
+
+function execHdc(args, timeout = 30000) {
+  return execFileSync(getHdcPath(), args, { timeout, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+
+function ensureDeviceConnected() {
+  const targets = execHdc(['list', 'targets']).split('\n').map(s => s.trim()).filter(Boolean);
+  if (targets.length > 0 && targets[0] !== '[Empty]') return;
+  try {
+    const port = parseInt(execFileSync('param', ['get', 'persist.hdc.port'], { timeout: 3000, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).trim(), 10);
+    if (port > 0 && execHdc(['tconn', `127.0.0.1:${port}`], 10000).includes('Connect OK')) return;
+  } catch {}
+  throw new Error('No HarmonyOS device connected. Enable Developer Options + Wireless Debugging.');
+}
+
+// ─── CDP ────────────────────────────────────────────────────────────────
+function buildCmdArgs(port, options = {}) {
+  const args = [
+    `--remote-debugging-port=${port}`,
+    `--remote-allow-origins=http://127.0.0.1:${port}`,
+  ];
+  for (const f of BOOL_FLAGS) args.push(`--${f}`);
+  args.push('--password-store=basic', '--use-mock-keychain', '--force-color-profile=srgb');
+  args.push(`--disable-features=${DISABLED_FEATURES}`);
+  if (options.userDataDir) args.push(`--user-data-dir=${options.userDataDir}`);
+  return args.join(' ');
+}
+
+function tryCdpEndpoint(url) {
+  return new Promise((resolve, reject) => {
+    const req = http.get(url, (res) => {
+      let d = '';
+      res.on('data', (c) => d += c);
+      res.on('end', () => {
+        if (res.statusCode !== 200) return reject(new Error(`HTTP ${res.statusCode}`));
+        try {
+          const j = JSON.parse(d);
+          j.webSocketDebuggerUrl ? resolve(j.webSocketDebuggerUrl) : reject(new Error('No webSocketDebuggerUrl'));
+        } catch { reject(new Error('Parse failed')); }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(2000, () => { req.destroy(); reject(new Error('Timeout')); });
+  });
+}
+
+async function waitForCdpEndpoint(port, timeoutMs = 30000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      return await tryCdpEndpoint(`http://127.0.0.1:${port}/json/version`);
+    } catch {
+      try {
+        return await tryCdpEndpoint(`http://[::1]:${port}/json/version`);
+      } catch {
+        await new Promise(r => setTimeout(r, 500));
+      }
+    }
+  }
+  throw new Error(`CDP endpoint timeout on port ${port} after ${timeoutMs}ms`);
+}
+
+// ─── launchBrowserViaCdp ────────────────────────────────────────────────
+// Cached browser instance (system browsers typically support single instance)
+let _cachedBrowser = null;
+let _launchPromise = null;
+
+async function launchBrowserViaCdp(options = {}) {
+  if (_cachedBrowser) return _cachedBrowser;
+  if (_launchPromise) return _launchPromise;
+
+  _launchPromise = (async () => {
+    const { pkg, ability } = resolveBrowser(options);
+    const port = options.cdpPort || options.debuggingPort || 9333;
+
+    // 1. Connect to device
+    ensureDeviceConnected();
+
+    // 2. Check browser installed
+    if (!execHdc(['shell', 'bm', 'dump', '-a']).includes(pkg)) {
+      throw new Error(
+        `Browser "${pkg}" is not installed. ` +
+        `Install Haitai browser, or set HARMONY_BROWSER=chrome for Chrome 鸿蒙版, ` +
+        `or pass options.harmonyBundleName.`
+      );
+    }
+
+    // 3. Stop stale browser process
+    try { execHdc(['shell', 'aa', 'force-stop', pkg]); } catch {}
+    await new Promise(r => setTimeout(r, 2000));
+
+    // 4. Launch browser with CDP port
+    const cmdArgs = buildCmdArgs(port, options);
+    execHdc(['shell', 'aa', 'start', '-b', pkg, '-a', ability, '--ps', 'cmdArgs', cmdArgs]);
+
+    // 5. Wait for CDP endpoint
+    const wsEndpoint = await waitForCdpEndpoint(port);
+
+    // 6. Connect via Playwright connectOverCDP
+    const { chromium } = require('playwright');
+    const browser = await chromium.connectOverCDP(`http://127.0.0.1:${port}`);
+
+    _cachedBrowser = browser;
+
+    // Override close to keep browser alive for reuse (single instance limitation)
+    browser.close = async () => {
+      // Don't actually close — keep cached for reuse. Process exit will clean up.
+    };
+
+    // Real cleanup on process exit
+    process.on('exit', () => {
+      try { execHdc(['shell', 'aa', 'force-stop', pkg]); } catch {}
+    });
+
+    return browser;
+  })();
+
+  try {
+    return await _launchPromise;
+  } finally {
+    _launchPromise = null;
+  }
+}
+
+// ─── loadPageUrl ─────────────────────────────────────────────────────────
+/**
+ * Load an HTML file into a page — uses setContent on HarmonyOS (file:// not accessible)
+ * Drop-in replacement for: await page.goto('file://' + filePath)
+ */
+async function loadPageUrl(page, url, options = {}) {
+  if (process.platform === 'openharmony' && url.startsWith('file://')) {
+    const filePath = url.replace(/^file:\/\//, '');
+    const fs = require('fs');
+    const html = fs.readFileSync(decodeURIComponent(filePath), 'utf-8');
+    await page.setContent(html, { waitUntil: options.waitUntil || 'load', timeout: options.timeout || 30000 });
+    return;
+  }
+  await page.goto(url, options);
+}
+
+// ─── Patch playwright-core (postinstall) ────────────────────────────────
+/**
+ * Patch playwright-core to support openharmony platform.
+ * Called from bin/ohos-postinstall.cjs during npm install.
+ */
+function patchPlaywrightCore() {
+  const fs = require('fs');
+  const path = require('path');
+
+  let pcRoot;
+  try {
+    pcRoot = path.dirname(require.resolve('playwright-core/package.json'));
+  } catch {
+    console.log('  [ohos-bridge] playwright-core not found, skipping patch');
+    return false;
+  }
+
+  const targetFile = path.join(pcRoot, 'lib', 'server', 'registry', 'index.js');
+  if (!fs.existsSync(targetFile)) {
+    console.log('  [ohos-bridge] registry/index.js not found, skipping patch');
+    return false;
+  }
+
+  let content = fs.readFileSync(targetFile, 'utf-8');
+  const MARKER = '/* @ohos-ports/slides-grab-patched */';
+
+  if (content.includes(MARKER)) {
+    console.log('  [ohos-bridge] Already patched');
+    return true;
+  }
+
+  // Patch: add openharmony to platform check
+  const oldCode = `else if (process.platform === "win32")
+      cacheDirectory = process.env.LOCALAPPDATA || import_path.default.join(import_os.default.homedir(), "AppData", "Local");
+    else
+      throw new Error("Unsupported platform: " + process.platform);`;
+
+  const newCode = `else if (process.platform === "win32")
+      cacheDirectory = process.env.LOCALAPPDATA || import_path.default.join(import_os.default.homedir(), "AppData", "Local");
+    else if (process.platform === "openharmony")
+      cacheDirectory = process.env.XDG_CACHE_HOME || import_path.default.join(import_os.default.homedir(), ".cache");
+    else
+      throw new Error("Unsupported platform: " + process.platform);`;
+
+  if (content.includes(oldCode)) {
+    content = MARKER + '\n' + content.replace(oldCode, newCode);
+    fs.writeFileSync(targetFile, content, 'utf-8');
+    console.log('  [ohos-bridge] ✓ Patched playwright-core registry/index.js');
+    return true;
+  }
+
+  console.log('  [ohos-bridge] ⚠ Could not find target code to patch (playwright version mismatch?)');
+  return false;
+}
+
+module.exports = { launchBrowserViaCdp, loadPageUrl, patchPlaywrightCore, resolveBrowser };

package/src/pptx-raster-export.cjs

@@ -0,0 +1,299 @@
+const PptxGenJS = require('pptxgenjs');
+// OHOS: Use system Haitai browser via CDP bridge instead of standalone Chromium
+const { launchBrowserViaCdp, loadPageUrl } = require('./ohos-browser-bridge.cjs');
+const path = require('path');
+const fs = require('fs');
+const sharp = require('sharp');
+
+const {
+  getResolutionChoices,
+  getResolutionSize,
+  normalizeResolutionPreset,
+} = require('./export-resolution.cjs');
+const {
+  DEFAULT_SLIDE_MODE,
+  getSlideModeChoices,
+  getSlideModeConfig,
+  normalizeSlideMode,
+} = require('./slide-mode.cjs');
+
+const DEFAULT_SLIDES_DIR = 'slides';
+const DEFAULT_OUTPUT = 'output.pptx';
+const DEFAULT_RESOLUTION = '2160p';
+const DEFAULT_CAPTURE_DEVICE_SCALE_FACTOR = 2;
+const TARGET_RASTER_DPI = 150;
+const SLIDE_FILE_PATTERN = /^slide-.*\.html$/i;
+
+function normalizeDimension(value, fallback) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return fallback;
+  }
+  return Math.max(1, Math.round(value));
+}
+
+function buildPageOptions(resolution = '', slideMode = DEFAULT_SLIDE_MODE) {
+  const { framePx } = getSlideModeConfig(slideMode);
+  const targetResolution = getResolutionSize(resolution, slideMode);
+  return {
+    viewport: {
+      width: framePx.width,
+      height: framePx.height,
+    },
+    deviceScaleFactor: targetResolution
+      ? targetResolution.height / framePx.height
+      : DEFAULT_CAPTURE_DEVICE_SCALE_FACTOR,
+  };
+}
+
+function getTargetRasterSize(resolution = '', slideMode = DEFAULT_SLIDE_MODE) {
+  const targetResolution = getResolutionSize(resolution, slideMode);
+  if (targetResolution) {
+    return targetResolution;
+  }
+
+  const { pptxSizeIn } = getSlideModeConfig(slideMode);
+  return {
+    width: Math.round(pptxSizeIn.width * TARGET_RASTER_DPI),
+    height: Math.round(pptxSizeIn.height * TARGET_RASTER_DPI),
+  };
+}
+
+function toSlideOrder(fileName) {
+  const match = fileName.match(/\d+/);
+  return match ? Number.parseInt(match[0], 10) : Number.POSITIVE_INFINITY;
+}
+
+function sortSlideFiles(a, b) {
+  const orderA = toSlideOrder(a);
+  const orderB = toSlideOrder(b);
+  if (orderA !== orderB) {
+    return orderA - orderB;
+  }
+  return a.localeCompare(b);
+}
+
+function getHtmlSlides(slidesDir) {
+  if (!fs.existsSync(slidesDir)) {
+    throw new Error(`Slides directory not found: ${slidesDir}`);
+  }
+
+  const files = fs.readdirSync(slidesDir)
+    .filter((fileName) => SLIDE_FILE_PATTERN.test(fileName))
+    .sort(sortSlideFiles);
+
+  if (files.length === 0) {
+    throw new Error(`No slide-*.html files found in ${slidesDir}`);
+  }
+
+  return files;
+}
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: node convert.cjs [options]',
+      '',
+      'Options:',
+      `  --slides-dir <path>  Slide directory (default: ${DEFAULT_SLIDES_DIR})`,
+      `  --output <path>      Output pptx path (default: ${DEFAULT_OUTPUT})`,
+      `  --mode <mode>        Slide mode: ${getSlideModeChoices().join('|')} (default: ${DEFAULT_SLIDE_MODE})`,
+      `  --resolution <preset> Raster size preset: ${getResolutionChoices().join('|')}|4k (default: ${DEFAULT_RESOLUTION})`,
+      '  -h, --help           Show this help message',
+    ].join('\n'),
+  );
+  process.stdout.write('\n');
+}
+
+function readOptionValue(args, index, optionName) {
+  const next = args[index + 1];
+  if (!next || next.startsWith('-')) {
+    throw new Error(`Missing value for ${optionName}.`);
+  }
+  return next;
+}
+
+function parseArgs(args) {
+  const options = {
+    slidesDir: DEFAULT_SLIDES_DIR,
+    output: DEFAULT_OUTPUT,
+    mode: DEFAULT_SLIDE_MODE,
+    resolution: DEFAULT_RESOLUTION,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '--slides-dir') {
+      options.slidesDir = readOptionValue(args, i, '--slides-dir');
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--slides-dir=')) {
+      options.slidesDir = arg.slice('--slides-dir='.length);
+      continue;
+    }
+
+    if (arg === '--output') {
+      options.output = readOptionValue(args, i, '--output');
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--output=')) {
+      options.output = arg.slice('--output='.length);
+      continue;
+    }
+
+    if (arg === '--mode') {
+      options.mode = normalizeSlideMode(readOptionValue(args, i, '--mode'));
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--mode=')) {
+      options.mode = normalizeSlideMode(arg.slice('--mode='.length));
+      continue;
+    }
+
+    if (arg === '--resolution') {
+      options.resolution = normalizeResolutionPreset(readOptionValue(args, i, '--resolution'));
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--resolution=')) {
+      options.resolution = normalizeResolutionPreset(arg.slice('--resolution='.length));
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (typeof options.slidesDir !== 'string' || options.slidesDir.trim() === '') {
+    throw new Error('--slides-dir must be a non-empty string.');
+  }
+
+  if (typeof options.output !== 'string' || options.output.trim() === '') {
+    throw new Error('--output must be a non-empty string.');
+  }
+
+  options.slidesDir = options.slidesDir.trim();
+  options.output = options.output.trim();
+  options.mode = normalizeSlideMode(options.mode);
+  options.resolution = normalizeResolutionPreset(options.resolution);
+  return options;
+}
+
+async function convertSlide(htmlFile, pres, browser, options = {}) {
+  const filePath = path.isAbsolute(htmlFile) ? htmlFile : path.join(process.cwd(), htmlFile);
+  const slideMode = normalizeSlideMode(options.mode || DEFAULT_SLIDE_MODE);
+  const fallbackSize = getSlideModeConfig(slideMode).framePx;
+
+  const page = await browser.newPage(buildPageOptions(options.resolution, slideMode));
+  await page.goto(`file://${filePath}`);
+
+  const bodyDimensions = await page.evaluate(() => {
+    const body = document.body;
+    const style = window.getComputedStyle(body);
+    return {
+      width: parseFloat(style.width),
+      height: parseFloat(style.height),
+    };
+  });
+
+  await page.setViewportSize({
+    width: normalizeDimension(bodyDimensions.width, fallbackSize.width),
+    height: normalizeDimension(bodyDimensions.height, fallbackSize.height),
+  });
+
+  const screenshot = await page.screenshot({ type: 'png' });
+  await page.close();
+
+  const targetSize = getTargetRasterSize(options.resolution, slideMode);
+
+  const resized = await sharp(screenshot)
+    .resize(targetSize.width, targetSize.height, { fit: 'fill' })
+    .png()
+    .toBuffer();
+
+  const tmpPath = path.join(process.env.TMPDIR || '/tmp', `slide-${Date.now()}-${Math.random().toString(36).slice(2)}.png`);
+  fs.writeFileSync(tmpPath, resized);
+
+  const slide = pres.addSlide();
+  slide.addImage({
+    path: tmpPath,
+    x: 0,
+    y: 0,
+    w: '100%',
+    h: '100%',
+  });
+
+  return tmpPath;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printUsage();
+    return;
+  }
+
+  const pres = new PptxGenJS();
+  const { pptxSizeIn } = getSlideModeConfig(options.mode);
+  pres.defineLayout({
+    name: 'SLIDES_GRAB_DYNAMIC',
+    width: pptxSizeIn.width,
+    height: pptxSizeIn.height,
+  });
+  pres.layout = 'SLIDES_GRAB_DYNAMIC';
+
+  const slidesDir = path.resolve(process.cwd(), options.slidesDir);
+  const { ensureSlidesPassValidation } = await import('../scripts/validate-slides.js');
+  await ensureSlidesPassValidation(slidesDir, { exportLabel: 'PPTX export', slideMode: options.mode });
+  const files = getHtmlSlides(slidesDir);
+
+  console.log(`Converting ${files.length} slides...`);
+
+  const browser = process.platform === 'openharmony'
+    ? await launchBrowserViaCdp()
+    : await require('playwright').chromium.launch();
+  const tmpFiles = [];
+
+  for (const file of files) {
+    const filePath = path.join(slidesDir, file);
+    console.log(`  Processing: ${file}`);
+    try {
+      const tmpPath = await convertSlide(filePath, pres, browser, { mode: options.mode, resolution: options.resolution });
+      tmpFiles.push(tmpPath);
+      console.log(`    ✓ ${file} done`);
+    } catch (error) {
+      console.error(`    ✗ ${file} error: ${error.message}`);
+    }
+  }
+
+  await browser.close();
+
+  const outputFile = path.resolve(process.cwd(), options.output);
+  await pres.writeFile({ fileName: outputFile });
+  console.log(`\nSaved: ${outputFile}`);
+
+  for (const filePath of tmpFiles) {
+    try {
+      fs.unlinkSync(filePath);
+    } catch {}
+  }
+}
+
+module.exports = {
+  buildPageOptions,
+  getHtmlSlides,
+  getTargetRasterSize,
+  main,
+  parseArgs,
+};

package/src/resolve.js

@@ -0,0 +1,110 @@
+/**
+ * Path resolution for slides-grab.
+ *
+ * Resolution order:
+ *   1. Local (user's CWD) — per-project overrides
+ *   2. Package root — built-in defaults
+ *
+ * slides directory, slide-outline.md → always local (CWD)
+ * templates/ → local first, package fallback
+ * scripts/ → always package
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..');
+
+/**
+ * Get the package root directory (where slides-grab is installed).
+ */
+export function getPackageRoot() {
+  return PACKAGE_ROOT;
+}
+
+/**
+ * Get the user's working directory (where slides are created).
+ */
+export function getCwd() {
+  return process.cwd();
+}
+
+/**
+ * Resolve the slides directory in CWD.
+ * @param {string} [slidesDir='slides'] - relative or absolute slides directory path
+ */
+export function getSlidesDir(slidesDir = process.env.PPT_AGENT_SLIDES_DIR || 'slides') {
+  return resolve(getCwd(), slidesDir);
+}
+
+/**
+ * Resolve a template file. Local first, then package fallback.
+ * @param {string} name — template name without extension (e.g. "cover")
+ * @returns {{ path: string, source: 'local' | 'package' } | null}
+ */
+export function resolveTemplate(name) {
+  const fileName = name.endsWith('.html') ? name : `${name}.html`;
+
+  const localPath = join(getCwd(), 'templates', fileName);
+  if (existsSync(localPath)) {
+    return { path: localPath, source: 'local' };
+  }
+
+  const packagePath = join(PACKAGE_ROOT, 'templates', fileName);
+  if (existsSync(packagePath)) {
+    return { path: packagePath, source: 'package' };
+  }
+
+  return null;
+}
+
+/**
+ * List all available templates (local + package, deduplicated).
+ * @returns {Array<{ name: string, source: 'local' | 'package' }>}
+ */
+export function listTemplates() {
+  const seen = new Map();
+
+  // Local templates first (take priority)
+  const localDir = join(getCwd(), 'templates');
+  if (existsSync(localDir)) {
+    for (const f of readdirSync(localDir)) {
+      if (f.endsWith('.html')) {
+        seen.set(f, { name: f.replace('.html', ''), source: 'local' });
+      }
+    }
+  }
+
+  // Also check local custom/ subdirectory
+  const localCustomDir = join(localDir, 'custom');
+  if (existsSync(localCustomDir)) {
+    for (const f of readdirSync(localCustomDir)) {
+      if (f.endsWith('.html')) {
+        const key = `custom/${f}`;
+        seen.set(key, { name: `custom/${f.replace('.html', '')}`, source: 'local' });
+      }
+    }
+  }
+
+  // Package templates (only if not already overridden)
+  const pkgDir = join(PACKAGE_ROOT, 'templates');
+  if (existsSync(pkgDir)) {
+    for (const f of readdirSync(pkgDir)) {
+      if (f.endsWith('.html') && !seen.has(f)) {
+        seen.set(f, { name: f.replace('.html', ''), source: 'package' });
+      }
+    }
+  }
+
+  return Array.from(seen.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Resolve a script path. Always from package.
+ * @param {string} relativePath — e.g. "scripts/validate-slides.js"
+ */
+export function resolveScript(relativePath) {
+  return join(PACKAGE_ROOT, relativePath);
+}