slides-grab 1.2.6 → 1.3.1

package/src/design-gate-report.js

@@ -0,0 +1,244 @@
+const PASS_A_SPEC = {
+  label: 'Pass A',
+  title: 'Pass A System Contract / Constraint Integrity',
+  titlePattern: /\bPass\s*A:?\s*System Contract\s*\/\s*Constraint Integrity\b/i,
+  checks: [
+    'System consistency',
+    'Color discipline',
+    'AI slop tropes',
+    'Content discipline',
+  ],
+};
+
+const PASS_B_SPEC = {
+  label: 'Pass B',
+  title: 'Pass B Audience Impact / Expressive Readability',
+  titlePattern: /\bPass\s*B:?\s*Audience Impact\s*\/\s*Expressive Readability\b/i,
+  checks: [
+    'Composition & hierarchy',
+    'Typography & legibility',
+    'Korean/CJK word-break integrity',
+    'Review Litmus',
+  ],
+};
+
+const CONFIDENCE_PATTERN = /^Confidence:\s*(High|Medium|Low)\s*$/im;
+const EVIDENCE_PATTERN = /^Evidence:\s*.+\.png\b.*$/im;
+const VERDICT_PATTERN = /^\s*VERDICT:\s*(\S+)\s*$/gim;
+const BLOCKING_FINDINGS_PATTERN = /^\s*Blocking findings:\s*(.+)$/gim;
+const UNRESOLVED_CRITICAL_PATTERN = /^\s*Unresolved Critical:\s*(\d+)\s*$/gim;
+const SUPPORTED_FINDING_SEVERITIES = new Set(['Major', 'Minor', 'Note']);
+
+export function assertProceedReportsComplete({ passAReport, passBReport, evidenceFiles = [], slideFingerprints = [] }) {
+  const validation = validateProceedReportsComplete({
+    passAReport,
+    passBReport,
+    evidenceFiles,
+    slideFingerprints,
+  });
+  if (validation.failures.length > 0) {
+    throw new Error(`Design gate cannot proceed: ${validation.failures.join(' ')}`);
+  }
+  return validation;
+}
+
+export function validateProceedReportsComplete({
+  passAReport,
+  passBReport,
+  evidenceFiles = [],
+  slideFingerprints = [],
+}) {
+  const passA = validateProceedReport(passAReport, PASS_A_SPEC, evidenceFiles, slideFingerprints);
+  const passB = validateProceedReport(passBReport, PASS_B_SPEC, evidenceFiles, slideFingerprints);
+  const failures = [
+    ...passA.failures,
+    ...passB.failures,
+  ];
+
+  return {
+    status: failures.length === 0 ? 'passed' : 'failed',
+    failures,
+    passA: passA.summary,
+    passB: passB.summary,
+  };
+}
+
+function validateProceedReport(report, spec, evidenceFiles, slideFingerprints) {
+  const failures = [];
+  const confidenceMatch = report.match(CONFIDENCE_PATTERN);
+  const criticalMatches = [...report.matchAll(UNRESOLVED_CRITICAL_PATTERN)];
+  const blockingMatches = [...report.matchAll(BLOCKING_FINDINGS_PATTERN)];
+  const verdict = parseVerdict(report);
+  const missingChecks = spec.checks.filter((check) => !hasPassedCheck(report, check));
+
+  if (!spec.titlePattern.test(report)) {
+    failures.push(`${spec.label} is missing required role title "${spec.title}".`);
+  }
+  failures.push(...validatePassVerdict(verdict, spec.label));
+  if (!CONFIDENCE_PATTERN.test(report)) {
+    failures.push(`${spec.label} is missing required Confidence: High|Medium|Low.`);
+  }
+  if (!EVIDENCE_PATTERN.test(report)) {
+    failures.push(`${spec.label} is missing required rendered PNG evidence reference.`);
+  }
+  failures.push(...validateEvidenceFiles(report, spec.label, evidenceFiles));
+  failures.push(...validateSlideFingerprints(report, spec.label, slideFingerprints));
+  failures.push(...validateFindingsTable(report, spec.label));
+
+  failures.push(...validateCriticalSummary(criticalMatches, blockingMatches, spec.label));
+  failures.push(...validateCriticalFindingRows(report, spec.label));
+  failures.push(...missingChecks.map((check) => `${spec.label} missing required passed check: ${check}.`));
+
+  return {
+    failures,
+    summary: {
+      label: spec.label,
+      verdict: verdict.values.length === 1 ? verdict.values[0] : '',
+      confidence: confidenceMatch?.[1] || '',
+      unresolvedCritical: summarizeUnresolvedCritical(criticalMatches),
+      blockingFindings: parseBlockingFindings(blockingMatches),
+      checks: spec.checks.map((check) => ({
+        name: check,
+        status: missingChecks.includes(check) ? 'missing' : 'pass',
+      })),
+      evidenceFiles: evidenceFiles.filter((fileName) => report.includes(fileName)),
+      slideFingerprints: slideFingerprints.filter((entry) => report.includes(entry.file) && report.includes(entry.sha256)),
+    },
+  };
+}
+
+function validateEvidenceFiles(report, label, evidenceFiles) {
+  return evidenceFiles
+    .filter((fileName) => !report.includes(fileName))
+    .map((fileName) => `${label} is missing rendered evidence file: ${fileName}.`);
+}
+
+function validateSlideFingerprints(report, label, slideFingerprints) {
+  return slideFingerprints
+    .filter((entry) => !report.includes(entry.file) || !report.includes(entry.sha256))
+    .map((entry) => `${label} is missing current slide fingerprint: ${entry.file}: ${entry.sha256}.`);
+}
+
+function validateFindingsTable(report, label) {
+  const headerPattern = /^\|\s*Slide\s*\|\s*Finding\s*\|\s*Severity\s*\|\s*Fix\s*\|\s*Status\s*\|/im;
+  const separatorPattern = /^\|\s*-+\s*\|\s*-+\s*\|\s*-+\s*\|\s*-+\s*\|\s*-+\s*\|/im;
+  const dataRows = parseFindingRows(report);
+  const failures = [];
+
+  if (!headerPattern.test(report)) {
+    failures.push(`${label} is missing required findings table columns: Slide | Finding | Severity | Fix | Status.`);
+  }
+  if (!separatorPattern.test(report)) {
+    failures.push(`${label} is missing required findings table separator row.`);
+  }
+  if (dataRows.length === 0) {
+    failures.push(`${label} is missing at least one findings table data row with a supported severity.`);
+  }
+  failures.push(...validateFindingRowSeverities(dataRows, label));
+
+  return failures;
+}
+
+function validateCriticalFindingRows(report, label) {
+  return parseFindingRows(report)
+    .filter((row) => row.severity.toLowerCase() === 'critical')
+    .map(() => `${label} lists a Critical severity finding and cannot proceed.`);
+}
+
+function validateFindingRowSeverities(rows, label) {
+  return rows
+    .filter((row) => !SUPPORTED_FINDING_SEVERITIES.has(row.severity))
+    .map((row) => `${label} lists unsupported finding severity "${row.severity}".`);
+}
+
+function validatePassVerdict(verdict, label) {
+  if (verdict.values.length === 0) {
+    return [`${label} is missing required "VERDICT: PASS".`];
+  }
+  if (verdict.values.length > 1) {
+    return [`${label} must include exactly one VERDICT line.`];
+  }
+  if (verdict.values[0] !== 'PASS') {
+    return [`${label} must use "VERDICT: PASS".`];
+  }
+  return [];
+}
+
+function parseVerdict(report) {
+  return {
+    values: [...report.matchAll(VERDICT_PATTERN)].map((match) => match[1].trim().toUpperCase()),
+  };
+}
+
+function parseFindingRows(report) {
+  const lines = report.split(/\r?\n/);
+  const headerIndex = lines.findIndex((line) => (
+    /^\|\s*Slide\s*\|\s*Finding\s*\|\s*Severity\s*\|\s*Fix\s*\|\s*Status\s*\|/i.test(line.trim())
+  ));
+  if (headerIndex === -1) return [];
+
+  const rows = [];
+  for (const rawLine of lines.slice(headerIndex + 1)) {
+    const line = rawLine.trim();
+    if (!line.startsWith('|')) {
+      if (line) break;
+      if (rows.length > 0) break;
+      continue;
+    }
+    const cells = line.split('|').slice(1, -1).map((cell) => cell.trim());
+    if (cells.length < 5) continue;
+    if (cells.every((cell) => /^-+$/.test(cell))) continue;
+    if (/^slide$/i.test(cells[0]) && /^finding$/i.test(cells[1])) continue;
+    rows.push({
+      slide: cells[0],
+      finding: cells[1],
+      severity: cells[2],
+      fix: cells[3],
+      status: cells[4],
+    });
+  }
+  return rows;
+}
+
+function validateCriticalSummary(criticalMatches, blockingMatches, label) {
+  const failures = [];
+
+  if (criticalMatches.length === 0) {
+    failures.push(`${label} is missing required Unresolved Critical: 0.`);
+  } else if (criticalMatches.length > 1) {
+    failures.push(`${label} must include exactly one Unresolved Critical line.`);
+  } else if (criticalMatches[0][1] !== '0') {
+    failures.push(`${label} has unresolved Critical findings and blocks proceed.`);
+  }
+
+  if (blockingMatches.length === 0) {
+    failures.push(`${label} is missing required Blocking findings: None.`);
+  } else if (blockingMatches.length > 1) {
+    failures.push(`${label} must include exactly one Blocking findings line.`);
+  } else if (blockingMatches[0][1].trim().toLowerCase() !== 'none') {
+    failures.push(`${label} has blocking findings and cannot proceed.`);
+  }
+
+  return failures;
+}
+
+function hasPassedCheck(report, check) {
+  const checkPattern = new RegExp(`^\\s*-\\s*\\[[xX]\\]\\s*${escapeRegex(check)}\\s*:\\s*PASS\\b`, 'im');
+  return checkPattern.test(report);
+}
+
+function summarizeUnresolvedCritical(matches) {
+  if (matches.length !== 1) return null;
+  return Number.parseInt(matches[0][1], 10);
+}
+
+function parseBlockingFindings(matches) {
+  if (matches.length !== 1) return null;
+  const value = matches[0][1].trim();
+  if (value.toLowerCase() === 'none') return [];
+  return [value];
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/design-gate-state.js

@@ -0,0 +1,294 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { basename, join, relative, resolve } from 'node:path';
+import { classifyImageSource, extractCssUrls } from './image-contract.js';
+
+const SLIDE_FILE_PATTERN = /^slide-.*\.html$/i;
+const GATE_DIR_NAME = '.slides-grab';
+const GATE_STATE_FILE = 'design-gate.json';
+const GATE_REPORT_FILE = 'design-gate-report.md';
+const GATE_PREVIEW_DIR = 'gate-preview';
+const PROCEED = 'proceed';
+const VALID_VERDICTS = new Set([PROCEED, 'revise', 'rethink']);
+
+export function normalizeGateVerdict(value) {
+  const verdict = String(value || '').trim().toLowerCase();
+  if (!VALID_VERDICTS.has(verdict)) {
+    throw new Error(`Unknown design gate verdict "${value}". Expected: proceed, revise, or rethink.`);
+  }
+  return verdict;
+}
+
+export function buildDesignGatePaths(slidesDir) {
+  const resolvedSlidesDir = resolve(process.cwd(), slidesDir);
+  const gateDir = join(resolvedSlidesDir, GATE_DIR_NAME);
+  return {
+    slidesDir: resolvedSlidesDir,
+    gateDir,
+    previewDir: join(gateDir, GATE_PREVIEW_DIR),
+    reportPath: join(gateDir, GATE_REPORT_FILE),
+    statePath: join(gateDir, GATE_STATE_FILE),
+  };
+}
+
+export async function findGateSlideFiles(slidesDir) {
+  const entries = await readdir(slidesDir, { withFileTypes: true });
+  const files = entries
+    .filter((entry) => entry.isFile() && SLIDE_FILE_PATTERN.test(entry.name))
+    .map((entry) => entry.name)
+    .sort(sortSlideFiles);
+
+  if (files.length === 0) {
+    throw new Error(`No slide-*.html files found in ${slidesDir}.`);
+  }
+  return files;
+}
+
+export async function collectSlideFingerprints(slidesDir) {
+  const resolvedSlidesDir = resolve(process.cwd(), slidesDir);
+  const files = await findGateSlideFiles(resolvedSlidesDir);
+  return Promise.all(files.map(async (fileName) => {
+    return {
+      file: fileName,
+      sha256: await hashFile(join(resolvedSlidesDir, fileName)),
+    };
+  }));
+}
+
+export async function collectLocalAssetFingerprints(slidesDir) {
+  const resolvedSlidesDir = resolve(process.cwd(), slidesDir);
+  const slideFiles = await findGateSlideFiles(resolvedSlidesDir);
+  const localAssets = new Set();
+
+  for (const fileName of slideFiles) {
+    const html = await readFile(join(resolvedSlidesDir, fileName), 'utf-8');
+    for (const source of extractLocalAssetSources(html)) {
+      localAssets.add(source);
+    }
+  }
+
+  return collectFileFingerprints(resolvedSlidesDir, Array.from(localAssets).sort(sortSlideFiles));
+}
+
+export async function collectFileFingerprints(baseDir, files) {
+  const resolvedBaseDir = resolve(process.cwd(), baseDir);
+  return Promise.all(files.map(async (fileName) => ({
+    file: fileName,
+    sha256: await hashFile(join(resolvedBaseDir, fileName)),
+  })));
+}
+
+export async function readDesignGateState(slidesDir) {
+  const { statePath } = buildDesignGatePaths(slidesDir);
+  if (!existsSync(statePath)) return null;
+
+  try {
+    return JSON.parse(await readFile(statePath, 'utf-8'));
+  } catch (error) {
+    throw new Error(`Design gate state is unreadable: ${statePath}. ${error.message}`);
+  }
+}
+
+export async function writeDesignGateState(slidesDir, state, reportMarkdown = '') {
+  const paths = buildDesignGatePaths(slidesDir);
+  await mkdir(paths.gateDir, { recursive: true });
+  await writeFile(paths.statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf-8');
+  if (reportMarkdown) {
+    await writeFile(paths.reportPath, reportMarkdown, 'utf-8');
+  }
+  return paths;
+}
+
+export async function createDesignGateState(options) {
+  const slidesDir = resolve(process.cwd(), options.slidesDir);
+  const verdict = normalizeGateVerdict(options.verdict);
+  const slideFingerprints = await collectSlideFingerprints(slidesDir);
+
+  return {
+    schemaVersion: 2,
+    verdict,
+    generatedAt: new Date().toISOString(),
+    slideMode: options.slideMode,
+    resolution: options.resolution,
+    previewDir: options.previewDir ? relative(slidesDir, options.previewDir) : join(GATE_DIR_NAME, GATE_PREVIEW_DIR),
+    reportPath: options.reportPath ? relative(slidesDir, options.reportPath) : join(GATE_DIR_NAME, GATE_REPORT_FILE),
+    passA: normalizeEvidence(options.passA),
+    passB: normalizeEvidence(options.passB),
+    gateValidation: options.gateValidation || { status: verdict === PROCEED ? 'passed' : 'not-run' },
+    slideFingerprints,
+    localAssetFingerprints: options.localAssetFingerprints || await collectLocalAssetFingerprints(slidesDir),
+    passReportFingerprints: options.passReportFingerprints || [],
+    previewFingerprints: options.previewFingerprints || [],
+  };
+}
+
+export async function assertDesignGateReady(slidesDir, options = {}) {
+  const label = options.label || 'export';
+  const paths = buildDesignGatePaths(slidesDir);
+  const state = await readDesignGateState(paths.slidesDir);
+  if (!state) {
+    throw new Error(`${label} blocked: run slides-grab design-gate and record a Proceed verdict before exporting.`);
+  }
+
+  if (normalizeGateVerdict(state.verdict) !== PROCEED) {
+    throw new Error(`${label} blocked: latest design gate verdict is "${state.verdict}", not "proceed".`);
+  }
+
+  if (state.schemaVersion !== 2) {
+    throw new Error(`${label} blocked: design gate receipt is from a legacy unenforced schema; rerun slides-grab design-gate.`);
+  }
+
+  if (state.gateValidation?.status !== 'passed') {
+    throw new Error(`${label} blocked: design gate report validation did not pass.`);
+  }
+
+  if (!state.passA?.reportPath || !state.passB?.reportPath) {
+    throw new Error(`${label} blocked: design gate state is missing dual-oracle Pass A/Pass B evidence.`);
+  }
+
+  assertPassReady(state.passA, 'Pass A', label);
+  assertPassReady(state.passB, 'Pass B', label);
+
+  const currentFingerprints = await collectSlideFingerprints(paths.slidesDir);
+  const previousFingerprints = Array.isArray(state.slideFingerprints) ? state.slideFingerprints : [];
+  const staleFiles = diffFingerprints(previousFingerprints, currentFingerprints);
+  if (staleFiles.length > 0) {
+    throw new Error(`${label} blocked: design gate is stale because slides changed: ${staleFiles.join(', ')}.`);
+  }
+
+  const localAssetFingerprints = Array.isArray(state.localAssetFingerprints) ? state.localAssetFingerprints : null;
+  if (!localAssetFingerprints) {
+    throw new Error(`${label} blocked: design gate receipt is missing local asset fingerprints; rerun slides-grab design-gate.`);
+  }
+  let currentAssetFingerprints = [];
+  try {
+    currentAssetFingerprints = await collectLocalAssetFingerprints(paths.slidesDir);
+  } catch (error) {
+    throw new Error(`${label} blocked: design gate is stale because local assets changed. ${error.message}`);
+  }
+  const staleAssets = diffFingerprints(localAssetFingerprints, currentAssetFingerprints);
+  if (staleAssets.length > 0) {
+    throw new Error(`${label} blocked: design gate is stale because local assets changed: ${staleAssets.join(', ')}.`);
+  }
+
+  const passReportFingerprints = Array.isArray(state.passReportFingerprints) ? state.passReportFingerprints : [];
+  if (passReportFingerprints.length < 2) {
+    throw new Error(`${label} blocked: design gate receipt is missing Pass A/Pass B report fingerprints.`);
+  }
+  const currentReportFingerprints = await collectFileFingerprints(paths.slidesDir, passReportFingerprints.map((entry) => entry.file));
+  const staleReports = diffFingerprints(passReportFingerprints, currentReportFingerprints);
+  if (staleReports.length > 0) {
+    throw new Error(`${label} blocked: design gate is stale because Pass A/Pass B reports changed: ${staleReports.join(', ')}.`);
+  }
+
+  const previewFingerprints = Array.isArray(state.previewFingerprints) ? state.previewFingerprints : [];
+  if (previewFingerprints.length === 0) {
+    throw new Error(`${label} blocked: design gate receipt is missing rendered evidence fingerprints.`);
+  }
+  const currentPreviewFingerprints = await collectFileFingerprints(paths.slidesDir, previewFingerprints.map((entry) => entry.file));
+  const stalePreviewFiles = diffFingerprints(previewFingerprints, currentPreviewFingerprints);
+  if (stalePreviewFiles.length > 0) {
+    throw new Error(`${label} blocked: design gate is stale because rendered evidence changed: ${stalePreviewFiles.join(', ')}.`);
+  }
+
+  return state;
+}
+
+export function buildDesignGateReport(state, passAReport, passBReport) {
+  return [
+    '# slides-grab Design Gate Report',
+    '',
+    `Verdict: ${state.verdict}`,
+    `Generated: ${state.generatedAt}`,
+    `Slide mode: ${state.slideMode}`,
+    `Resolution: ${state.resolution}`,
+    '',
+    '## Pass A: System Contract / Constraint Integrity',
+    '',
+    passAReport.trim(),
+    '',
+    '## Pass B: Audience Impact / Expressive Readability',
+    '',
+    passBReport.trim(),
+    '',
+    '## Slide Fingerprints',
+    '',
+    ...state.slideFingerprints.map((entry) => `- ${entry.file}: ${entry.sha256}`),
+    '',
+  ].join('\n');
+}
+
+function normalizeEvidence(value = {}) {
+  return {
+    reportPath: value.reportPath || '',
+    summary: value.summary || '',
+    verdict: value.verdict || '',
+    unresolvedCritical: value.unresolvedCritical ?? null,
+    blockingFindings: Array.isArray(value.blockingFindings) ? value.blockingFindings : [],
+    checks: Array.isArray(value.checks) ? value.checks : [],
+    evidenceFiles: Array.isArray(value.evidenceFiles) ? value.evidenceFiles : [],
+    slideFingerprints: Array.isArray(value.slideFingerprints) ? value.slideFingerprints : [],
+  };
+}
+
+function extractLocalAssetSources(html) {
+  const sources = new Set();
+  const attributePattern = /\b(?:src|poster)\s*=\s*(['"])(.*?)\1/gi;
+  let match;
+
+  while ((match = attributePattern.exec(html)) !== null) {
+    addLocalAssetSource(sources, match[2]);
+  }
+
+  for (const source of extractCssUrls(html)) {
+    addLocalAssetSource(sources, source);
+  }
+
+  return Array.from(sources);
+}
+
+function addLocalAssetSource(sources, source) {
+  const value = String(source || '').trim();
+  if (classifyImageSource(value).kind === 'local-asset-path') {
+    sources.add(value);
+  }
+}
+
+async function hashFile(filePath) {
+  const bytes = await readFile(filePath);
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function assertPassReady(pass, passLabel, exportLabel) {
+  if (pass.verdict !== 'PASS') {
+    throw new Error(`${exportLabel} blocked: ${passLabel} did not record VERDICT: PASS.`);
+  }
+  if (pass.unresolvedCritical !== 0) {
+    throw new Error(`${exportLabel} blocked: ${passLabel} has unresolved Critical findings.`);
+  }
+  if (pass.blockingFindings.length > 0) {
+    throw new Error(`${exportLabel} blocked: ${passLabel} has blocking findings.`);
+  }
+}
+
+function toSlideOrder(fileName) {
+  const match = basename(fileName).match(/\d+/);
+  return match ? Number.parseInt(match[0], 10) : Number.POSITIVE_INFINITY;
+}
+
+function sortSlideFiles(left, right) {
+  const leftOrder = toSlideOrder(left);
+  const rightOrder = toSlideOrder(right);
+  if (leftOrder !== rightOrder) return leftOrder - rightOrder;
+  return left.localeCompare(right);
+}
+
+function diffFingerprints(previous, current) {
+  const previousByFile = new Map(previous.map((entry) => [entry.file, entry.sha256]));
+  const currentByFile = new Map(current.map((entry) => [entry.file, entry.sha256]));
+  const files = new Set([...previousByFile.keys(), ...currentByFile.keys()]);
+  return Array.from(files)
+    .filter((file) => previousByFile.get(file) !== currentByFile.get(file))
+    .sort(sortSlideFiles);
+}

package/src/design-import.js

@@ -0,0 +1,164 @@
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const DEFAULT_MAX_BYTES = 256 * 1024;
+const ALLOWED_PROTOCOLS = new Set(['https:']);
+
+function getHeader(headers, name) {
+  if (!headers) return '';
+  if (typeof headers.get === 'function') return headers.get(name) ?? '';
+  return headers[name] ?? headers[name.toLowerCase()] ?? '';
+}
+
+function validateFinalDesignUrl(rawUrl, { allowedProtocols = ALLOWED_PROTOCOLS } = {}) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch (cause) {
+    throw new DesignImportError(`Invalid final URL after redirects: ${rawUrl}`, { cause });
+  }
+  if (!allowedProtocols.has(url.protocol)) {
+    throw new DesignImportError(
+      `Redirect final URL protocol ${url.protocol} is not allowed. Allowed: ${[...allowedProtocols].join(', ')}`,
+    );
+  }
+  return url;
+}
+
+async function readResponseBody(response, { maxBytes }) {
+  if (response.body && typeof response.body.getReader === 'function') {
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const chunk = Buffer.from(value);
+        total += chunk.byteLength;
+        if (total > maxBytes) {
+          if (typeof reader.cancel === 'function') {
+            await reader.cancel().catch(() => {});
+          }
+          throw new DesignImportError(
+            `DESIGN.md exceeds max size (${total} > ${maxBytes} bytes).`,
+          );
+        }
+        chunks.push(chunk);
+      }
+    } finally {
+      if (typeof reader.releaseLock === 'function') reader.releaseLock();
+    }
+    return Buffer.concat(chunks, total);
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+  if (buffer.byteLength > maxBytes) {
+    throw new DesignImportError(
+      `DESIGN.md exceeds max size (${buffer.byteLength} > ${maxBytes} bytes).`,
+    );
+  }
+  return buffer;
+}
+
+export class DesignImportError extends Error {
+  constructor(message, { cause } = {}) {
+    super(message);
+    this.name = 'DesignImportError';
+    if (cause) this.cause = cause;
+  }
+}
+
+export function validateDesignUrl(rawUrl, { allowedProtocols = ALLOWED_PROTOCOLS } = {}) {
+  if (typeof rawUrl !== 'string' || rawUrl.trim() === '') {
+    throw new DesignImportError('Design URL is required.');
+  }
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch (cause) {
+    throw new DesignImportError(`Invalid URL: ${rawUrl}`, { cause });
+  }
+  if (!allowedProtocols.has(url.protocol)) {
+    throw new DesignImportError(
+      `URL protocol ${url.protocol} is not allowed. Allowed: ${[...allowedProtocols].join(', ')}`,
+    );
+  }
+  return url;
+}
+
+export async function fetchDesignMarkdown(rawUrl, options = {}) {
+  const {
+    fetchImpl = globalThis.fetch,
+    maxBytes = DEFAULT_MAX_BYTES,
+    timeoutMs = 15000,
+    allowedProtocols,
+  } = options;
+
+  if (typeof fetchImpl !== 'function') {
+    throw new DesignImportError('No fetch implementation available; Node.js >= 18 required.');
+  }
+  const url = validateDesignUrl(rawUrl, { allowedProtocols });
+
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+
+  let response;
+  try {
+    response = await fetchImpl(url.toString(), {
+      redirect: 'follow',
+      signal: controller.signal,
+      headers: { 'User-Agent': 'slides-grab/import-design (+https://github.com/NomaDamas/slides-grab)' },
+    });
+
+    const finalUrl = validateFinalDesignUrl(response.url ?? url.toString(), { allowedProtocols });
+
+    if (!response.ok) {
+      throw new DesignImportError(`Fetch returned HTTP ${response.status} for ${url}`);
+    }
+
+    const contentType = getHeader(response.headers, 'content-type');
+    const looksLikeText = contentType === '' ||
+      contentType.includes('text/') ||
+      contentType.includes('markdown') ||
+      contentType.includes('application/octet-stream');
+    if (!looksLikeText) {
+      throw new DesignImportError(
+        `Refusing to import non-text response (content-type: ${contentType}).`,
+      );
+    }
+
+    const buffer = await readResponseBody(response, { maxBytes });
+    const text = buffer.toString('utf8');
+    return {
+      url: finalUrl.toString(),
+      contentType,
+      bytes: buffer.byteLength,
+      fetchedAt: new Date().toISOString(),
+      text,
+    };
+  } catch (cause) {
+    if (cause instanceof DesignImportError) throw cause;
+    throw new DesignImportError(`Fetch failed for ${url}: ${cause.message}`, { cause });
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+}
+
+export function formatImportedDesignMarkdown({ url, content, fetchedAt }) {
+  const banner = [
+    '<!--',
+    `  Imported by slides-grab import-design`,
+    `  source: ${url}`,
+    `  fetched-at: ${fetchedAt}`,
+    '-->',
+    '',
+  ].join('\n');
+  return `${banner}${content}\n`;
+}
+
+export function saveImportedDesign({ outputPath, markdown }) {
+  const absolutePath = resolve(outputPath);
+  writeFileSync(absolutePath, markdown, 'utf8');
+  return absolutePath;
+}